目的

创建一个名为`man`的内联宏，用于链接到另一个man页面。

sample-with-man-link.adoc

查看 man:gittutorial[7] 以开始。

手册页内联宏

class ManInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
  use_dsl

named :man
name_positional_attributes 'volnum'

def process parent, target, attrs
    doc = parent.document
    text = manname = target
    suffix = (volnum = attrs['volnum']) ? %((#{volnum})) : ''
    if doc.basebackend? 'html'
      target = %(#{manname}#{doc.outfilesuffix})
      doc.register :links, target
      node = create_anchor parent, text, type: :link, target: target
    elsif doc.backend == 'manpage'
      node = create_inline parent, :quoted, manname, type: :strong
    else
      node = create_inline parent, :quoted, manname
    end
    create_inline parent, :quoted, %(#{node.convert}#{suffix})
  end
end

用法

Asciidoctor::Extensions.register do
  inline_macro ManInlineMacro
end

Asciidoctor.convert_file 'sample-with-man-link.adoc', safe: :safe

小贴士与技巧

应用替换

当内联宏被处理时，大多数替换已经被应用（因为宏是最后被应用的替换之一）。为了让处理器应用替换到扩展返回的Inline节点的文本中，你必须在节点实例本身指定那些扩展。

您可以使用`subs`属性指定要对节点文本应用的替换。这个属性接受一个符号、一组符号或一个逗号分隔的字符串。

假设我们希望对文本应用正常的替换。以下是可以实现的方式：

create_inline_pass parent, '*https://example.org[Learn more]*',
  attributes: { 'subs' => :normal }

这个内嵌直通节点将生成一个链接，该链接的链接文本具有强调效果（即，加粗）。

您也可以将替换指定为一个字符串，该字符串的解析方式与块上的subs属性的值一样。

create_inline_pass parent, '*https://example.org[Learn more]*', attributes: { 'subs' => 'quotes,macros' }

你可以指定你想要应用的任何替换，以及它们应用的顺序。

你也可以创建一个应用了额外替换的格式化文本范围，而不是创建一个内联直通节点。

create_inline parent, :quoted, 'https://asciidoctor.org is _awesome_!',
  attributes: { 'subs' => :quotes }

:quoted` 主要类型代表一段格式化的文本。在这种情况下，我们不需要应用 macros 替换，因为链接还没有被转换。