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>
60 lines
1.5 KiB
Text
60 lines
1.5 KiB
Text
EXTRA_DIST += \
|
|
doc/modules/man/pages/cockpit.1.adoc \
|
|
doc/modules/man/pages/cockpit-bridge.1.adoc \
|
|
doc/modules/man/pages/cockpit-desktop.1.adoc \
|
|
doc/modules/man/pages/cockpit-ws.8.adoc \
|
|
doc/modules/man/pages/cockpit-tls.8.adoc \
|
|
doc/modules/man/pages/cockpit.conf.5.adoc \
|
|
doc/modules/man/pages/pam_ssh_add.8.adoc \
|
|
doc/modules/man/partials/author.adoc \
|
|
doc/modules/man/partials/bugs.adoc \
|
|
$(NULL)
|
|
|
|
MANPAGES = \
|
|
doc/output/man/cockpit.1 \
|
|
doc/output/man/cockpit-bridge.1 \
|
|
doc/output/man/cockpit-desktop.1 \
|
|
doc/output/man/cockpit-ws.8 \
|
|
doc/output/man/cockpit-tls.8 \
|
|
doc/output/man/cockpit.conf.5 \
|
|
doc/output/man/pam_ssh_add.8 \
|
|
$(NULL)
|
|
|
|
if ENABLE_DOC
|
|
|
|
ASCIIDOC_EXTENSIONS = \
|
|
doc/extensions/man-inline-macro.rb \
|
|
$(NULL)
|
|
|
|
dist_noinst_DATA += \
|
|
$(ASCIIDOC_EXTENSIONS) \
|
|
$(NULL)
|
|
|
|
man_MANS += \
|
|
$(MANPAGES) \
|
|
$(NULL)
|
|
CLEANFILES += $(MANPAGES)
|
|
|
|
# Some distros don't have asciidoctor and we need to prebundle the man pages
|
|
EXTRA_DIST += $(MANPAGES)
|
|
|
|
MAN_ASCIIDOC_ARGS = \
|
|
-a doctype="manpage" \
|
|
-a manmanual="cockpit" \
|
|
-a mansource="cockpit" \
|
|
$(patsubst %,-r $(srcdir)/%,${ASCIIDOC_EXTENSIONS}) \
|
|
$(NULL)
|
|
|
|
MAN_PROC = mkdir -p doc/output/man/ && $(ASCIIDOCTOR) $(MAN_ASCIIDOC_ARGS) -b manpage -o $@ $<
|
|
render-man:
|
|
mkdir -p doc/output/man
|
|
asciidoctor $(MAN_ASCIIDOC_ARGS) -b manpage -D doc/output/man doc/modules/man/pages/*.adoc
|
|
|
|
doc/output/man/%: doc/modules/man/pages/%.adoc
|
|
$(AM_V_GEN) $(MAN_PROC)
|
|
|
|
CLEAN_LOCAL_TARGETS += clean-man
|
|
clean-man:
|
|
rm -rf doc/output/man
|
|
|
|
endif ENABLE_DOC
|