mirror of
https://github.com/cockpit-project/cockpit.git
synced 2026-11-03 21:49:50 -09:00
acf9af315c
Adds a new extension for AsciiDoctor in `doc/extensions/man-inline-macro.rb` followed by a README in the same directory. This changes the links to manpages during compilation from asciidoc files into HTML or Manpages so that links work within HTML pages as well as being properly formatted within manpages. This started as an initial workaround to handle Antora xref extension to AsciiDoctor wherein it introduces resource ids such as module, version, and component. Ultimately this breaks AsciiDoctor parsing of xref and makes it think that it is a strange URI and not a URL. However as Cockpit guide only has links to manpages and the fact that this also improves system manpages a macro `man` suits better. Using this is fairly straightforward, when you want to reference a manpage within the Cockpit Guide or within a manpage you define it using `man:manpage-name[sub-volume]` which will then be translated to an anchor link in HTML or bold text in Manpage format with the text `manpage-name(sub-volume)`. This does not fix the links within Antora and building them locally within Cockpit repo using our instructions in doc/README.md will make the links show as unformatted text `man:manpage-name[sub-volume]`. This is not an issue within our cockpit-docs repo as we have an extension there that replaces the manpage macros with the proper xref module link for Antora. See-also: https://docs.antora.org/antora/latest/page/xref/#structure See-also: https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/main/lib/man-inline-macro/extension.rb Related-to: https://github.com/cockpit-project/cockpit-docs/pull/8 Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
40 lines
1.2 KiB
Ruby
40 lines
1.2 KiB
Ruby
require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
|
|
|
|
include Asciidoctor
|
|
|
|
# An inline macro that generates links to related man pages.
|
|
# For HTML it only generates links to Cockpit man pages as that is what
|
|
# is compiled. But you are able to use man:systemd[1], but it just
|
|
# won't get a link.
|
|
#
|
|
# Usage:
|
|
#
|
|
# man:gittutorial[7]
|
|
#
|
|
class ManInlineMacro < Extensions::InlineMacroProcessor
|
|
use_dsl
|
|
|
|
named :man
|
|
name_positional_attributes 'volnum'
|
|
|
|
def process parent, target, attrs
|
|
text = manname = target
|
|
suffix = ''
|
|
volnum = attrs['volnum']
|
|
target = %(#{manname}.#{volnum}.html)
|
|
suffix = %((#{volnum}))
|
|
if parent.document.basebackend?('html') && manname.start_with?('cockpit')
|
|
parent.document.register :links, target
|
|
node = create_anchor parent, text, type: :link, target: target
|
|
elsif parent.document.backend == 'manpage'
|
|
node = create_inline parent, :quoted, manname, type: :strong
|
|
else
|
|
node = create_inline parent, :quoted, manname
|
|
end
|
|
suffix ? (create_inline parent, :quoted, %(#{node.convert}#{suffix})) : node
|
|
end
|
|
end
|
|
|
|
Asciidoctor::Extensions.register do
|
|
inline_macro ManInlineMacro
|
|
end
|