From: Ian Wienand Date: Wed, 16 Oct 2024 23:15:09 +0000 (+1100) Subject: docs: link man pages in doc site X-Git-Tag: 106~281 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=144a243d2135efcf7bd62c7ea007e000fcd75f8d;p=thirdparty%2Fdracut-ng.git docs: link man pages in doc site Currently the man pages in the generated doc site don't link to each other. A standard link: approach doesn't work that well when the target is both a groff man page and the HTML site, as you don't want the links in the man page. This is something other projects have faced, git in particular uses adoc for man pages and the approach here is styled on its "gitlink:" macro. The .js version is for Antora which uses the asciidoctorjs internally and there is an asciidoc plugin for the man page generation. The ruby version is included just in case we want to geneate man pages from asciidoctor directly one day. For the HTML output it is a link to the page (or, can be marked for external looukup for other tools). For the man pages, it's just a usual "strong" text. I've been through the existing references to convert them to the new macro. --- diff --git a/Makefile b/Makefile index 3ca3bc5af..71272687b 100644 --- a/Makefile +++ b/Makefile @@ -120,7 +120,7 @@ endif %.xml: %.adoc @rm -f -- "$@" - asciidoc -a "version=$(DRACUT_FULL_VERSION)" -d manpage -b docbook -o "$@" $< + asciidoc -f man/asciidoc.conf -a "version=$(DRACUT_FULL_VERSION)" -d manpage -b docbook -o "$@" $< # If ANOTRA_BIN not set, default to look for "npx" to run "npx antora". If we # end up with undefined ANTORA_BIN (i.e. not set and npx not found), we'll give diff --git a/antora-playbook.yml b/antora-playbook.yml index 0e55e9f9a..a316fac89 100644 --- a/antora-playbook.yml +++ b/antora-playbook.yml @@ -15,3 +15,7 @@ runtime: log: # In C terms, -Werror failure_level: warn + +asciidoc: + extensions: + - ./doc_site/extensions/man.js diff --git a/doc_site/extensions/man.js b/doc_site/extensions/man.js new file mode 100644 index 000000000..65fb59261 --- /dev/null +++ b/doc_site/extensions/man.js @@ -0,0 +1,28 @@ +/* Example use + * + * man:page[N,external] + * + * N: section + * external: optional arg, links to external man page + * + */ +module.exports = function(registry) { + registry.inlineMacro('man', function() { + var self = this + self.process(function (parent, target, attrs) { + let section = attrs.$positional[0] === undefined ? '' : attrs.$positional[0]; + let internal = attrs.$positional[1] === undefined ? true : false + const attributes = {} + const content = `${target}(${section})` + let url + if (internal) { + url = `${target}.${section}.html` + } else { + url = `https://manpages.ubuntu.com/man${section}/${target}.${section}.html` + } + return self.createInline(parent, 'anchor', + content, { type: 'link', target: url, attributes }) + }) + }) +} + diff --git a/doc_site/extensions/man.rb b/doc_site/extensions/man.rb new file mode 100644 index 000000000..1f4386efb --- /dev/null +++ b/doc_site/extensions/man.rb @@ -0,0 +1,43 @@ +# Borrowed from +# https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/main/lib/man-inline-macro.rb + +require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal' + +include Asciidoctor + +# An inline macro that generates links to related man pages. +# +# 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 = '' + target = %(#{manname}.html) + if (volnum = attrs['volnum']) + suffix = %((#{volnum})) + end + if parent.document.basebackend? 'html' + 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 + +Extensions.register :uri_schemes do + inline_macro ManInlineMacro + # The following alias allows this macro to be used with the git man pages + inline_macro ManInlineMacro, :linkgit +end diff --git a/man/asciidoc.conf b/man/asciidoc.conf new file mode 100644 index 000000000..1498280e8 --- /dev/null +++ b/man/asciidoc.conf @@ -0,0 +1,81 @@ +## man: macro +# +# Usage: man:command[manpage-section] +# +# Note, {0} is the manpage section, while {target} is the command. +# +# Show man link as: (
); if section is defined, else just show +# the command. +# +# NOTE(ianw): lightly modified from +# https://github.com/git/git/blob/master/Documentation/asciidoc.conf#L10 + +[macros] +(?su)[\\]?(?Pman):(?P\S*?)\[(?P.*?)(,external)?\]= + +[attributes] +asterisk=* +plus=+ +caret=^ +startsb=[ +endsb=] +backslash=\ +tilde=~ +apostrophe=' +backtick=` +litdd=-- + +ifdef::backend-docbook[] +[man-inlinemacro] +{0%{target}} +{0#} +{0#{target}{0}} +{0#} +endif::backend-docbook[] + +ifdef::backend-docbook[] +ifdef::doctype-manpage[] +# The following two small workarounds insert a simple paragraph after screen +[listingblock] +{title} + +| + +{title#} + +[verseblock] +{title} +{title%} +{title#} +| + +{title#} +{title%} +endif::doctype-manpage[] +endif::backend-docbook[] + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] + + +{mantitle} +{manvolnum} +{mansource} +{manversion} +{manmanual} + + + {manname} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] + +ifdef::backend-xhtml11[] +[attributes] +git-relative-html-prefix= +[man-inlinemacro] +{target}{0?({0})} +endif::backend-xhtml11[] diff --git a/man/dracut-catimages.8.adoc b/man/dracut-catimages.8.adoc index f3c74a924..2e7f10e3d 100644 --- a/man/dracut-catimages.8.adoc +++ b/man/dracut-catimages.8.adoc @@ -55,4 +55,4 @@ link:$$https://github.com/dracut-ng/dracut-ng$$[https://github.com/dracut-ng/dra SEE ALSO -------- -*dracut*(8) +man:dracut[8] diff --git a/man/dracut.8.adoc b/man/dracut.8.adoc index ea3e080c9..2ff65d91c 100644 --- a/man/dracut.8.adoc +++ b/man/dracut.8.adoc @@ -31,7 +31,7 @@ early userspace. Initramfs images are also called "initrd". -For a complete list of kernel command line options see *dracut.cmdline*(7). +For a complete list of kernel command line options see man:dracut.cmdline[7]. If you are dropped to an emergency shell, while booting your initramfs, the file _/run/initramfs/rdsosreport.txt_ is created, which can be saved to a @@ -619,7 +619,7 @@ and no /etc/cmdline/*.conf will be generated into the initramfs. **--enhanced-cpio**:: Attempt to use the dracut-cpio binary, which optimizes archive creation for - copy-on-write filesystems by using the copy_file_range(2) syscall via Rust's + copy-on-write filesystems by using the man:copy_file_range[2] syscall via Rust's io::copy(). When specified, initramfs archives are also padded to ensure optimal data alignment for extent sharing. To retain reflink data deduplication benefits, this should be used alongside the **--no-compress** @@ -780,4 +780,4 @@ Warren Togami SEE ALSO -------- -*dracut.cmdline*(7) *dracut.conf*(5) *lsinitrd*(1) +man:dracut.cmdline[7] man:dracut.conf[5] man:lsinitrd[1] diff --git a/man/dracut.bootup.7.adoc b/man/dracut.bootup.7.adoc index b2aba6a0f..99f56ed16 100644 --- a/man/dracut.bootup.7.adoc +++ b/man/dracut.bootup.7.adoc @@ -124,4 +124,4 @@ Harald Hoyer SEE ALSO -------- -*dracut*(8) *bootup*(7) +man:dracut[8] man:bootup[7,external] diff --git a/man/dracut.cmdline.7.adoc b/man/dracut.cmdline.7.adoc index d646a74c0..17cfe8b27 100644 --- a/man/dracut.cmdline.7.adoc +++ b/man/dracut.cmdline.7.adoc @@ -336,10 +336,10 @@ crypto LUKS - key on removable device support NB: If systemd is included in the dracut initrd, dracut's built in removable device keying support won't work. systemd will prompt for a password from the console even if you've supplied **rd.luks.key**. -You may be able to use standard systemd *fstab*(5) syntax to +You may be able to use standard systemd man:fstab[5,external] syntax to get the same effect. If you do need **rd.luks.key** to work, you will have to exclude the "systemd" dracut module and any modules -that depend on it. See *dracut.conf*(5) and +that depend on it. See man:dracut.conf[5] and https://bugzilla.redhat.com/show_bug.cgi?id=905683 for more information. @@ -581,7 +581,7 @@ USB Android phone:: The following options are supported by the 'network-legacy' dracut module. Other network modules might support a slightly different set of options; refer to the documentation of the specific network module in use. For -NetworkManager, see *nm-initrd-generator*(8). +NetworkManager, see man:nm-initrd-generator[8]. **ip=**__{dhcp|on|any|dhcp6|auto6|either6|link6|single-dhcp}__:: dhcp|on|any::: get ip from dhcp server from all interfaces. If netroot=dhcp, @@ -696,7 +696,7 @@ interface name. Better name it "bootnet" or "bluesocket". **team=**____:____[:____]:: Setup team device on top of . is a comma-separated list of physical (ethernet) interfaces. - is the runner type to be used (see *teamd.conf*(5)); defaults to + is the runner type to be used (see man:teamd.conf[5,external]); defaults to activebackup. Team without parameters assumes team=team0:eth0,eth1:activebackup @@ -1465,4 +1465,4 @@ Harald Hoyer SEE ALSO -------- -*dracut*(8) *dracut.conf*(5) +man:dracut[8] man:dracut.conf[5] diff --git a/man/dracut.conf.5.adoc b/man/dracut.conf.5.adoc index babd8daa6..9e840ae85 100644 --- a/man/dracut.conf.5.adoc +++ b/man/dracut.conf.5.adoc @@ -344,4 +344,4 @@ Harald Hoyer See Also -------- -*dracut*(8) *dracut.cmdline*(7) +man:dracut[8] man:dracut.cmdline[7] diff --git a/man/dracut.modules.7.adoc b/man/dracut.modules.7.adoc index 9f1999420..7c2dbd9a0 100644 --- a/man/dracut.modules.7.adoc +++ b/man/dracut.modules.7.adoc @@ -353,4 +353,4 @@ Harald Hoyer SEE ALSO -------- -*dracut*(8) +man:dracut[8] diff --git a/man/dracut.usage.adoc b/man/dracut.usage.adoc index 2e2592ef7..79efad4d9 100644 --- a/man/dracut.usage.adoc +++ b/man/dracut.usage.adoc @@ -72,7 +72,7 @@ include ld.so.conf.d/*.conf == Adding dracut Modules Some dracut modules are turned off by default and have to be activated manually. You can do this by adding the dracut modules to the configuration file -_/etc/dracut.conf_ or _/etc/dracut.conf.d/myconf.conf_. See *dracut.conf*(5). +_/etc/dracut.conf_ or _/etc/dracut.conf.d/myconf.conf_. See man:dracut.conf[5] You can also add dracut modules on the command line by using the `-a` or `--add` option: @@ -95,7 +95,7 @@ distribution configuration file). Sometimes you don't want a dracut module to be included for reasons of speed, size or functionality. To do this, either specify the omit_dracutmodules variable in the _dracut.conf_ or _/etc/dracut.conf.d/myconf.conf_ configuration -file (see *dracut.conf*(5)), or use the `-o` or `--omit` option +file (see man:dracut.conf[5]) or use the `-o` or `--omit` option on the command line: [,console] @@ -107,7 +107,7 @@ on the command line: If you need a special kernel module in the initramfs, which is not automatically picked up by dracut, you have the use the --add-drivers option on the command line or the drivers variable in the _/etc/dracut.conf_ -or _/etc/dracut.conf.d/myconf.conf_ configuration file (see *dracut.conf*(5)): +or _/etc/dracut.conf.d/myconf.conf_ configuration file (see man:dracut.conf[5]): [,console] ---- @@ -132,7 +132,7 @@ The kernel command line can also be provided by the dhcp server with the root-path option. See <>. For a full reference of all kernel command line parameters, -see *dracut.cmdline*(7). +see man:dracut.cmdline[7]. To get a quick start for the suitable kernel command line on your system, use the __--print-cmdline__ option: @@ -538,7 +538,7 @@ the dracut shell [[additional-dracut-boot-parameters]] === Additional dracut boot parameters -For more debugging options, see *dracut.cmdline*(7). +For more debugging options, see man:dracut.cmdline[7]. [[debugging-dracut-on-shutdown]] diff --git a/man/lsinitrd.1.adoc b/man/lsinitrd.1.adoc index 90ebb634e..10a9d5647 100644 --- a/man/lsinitrd.1.adoc +++ b/man/lsinitrd.1.adoc @@ -64,4 +64,4 @@ Nikoli SEE ALSO -------- -*dracut*(8) +man:dracut[8]