mirror of
https://github.com/cockpit-project/cockpit.git
synced 2026-11-03 21:49:50 -09:00
asciidoc: Add inline manpage macro extension
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>
This commit is contained in:
Freya Gustavsson
parent
853335bea8
commit
acf9af315c
12 changed files with 88 additions and 22 deletions
|
|
@ -65,10 +65,15 @@ MAN_ADOC_FILES = \
|
|||
doc/modules/man/pages/pam_ssh_add.8.adoc \
|
||||
$(NULL)
|
||||
|
||||
ASCIIDOC_EXTENSIONS = \
|
||||
doc/extensions/man-inline-macro.rb \
|
||||
$(NULL)
|
||||
|
||||
dist_noinst_DATA += \
|
||||
$(GUIDE_MAIN_ADOC_FILE) \
|
||||
$(MAN_ADOC_FILES) \
|
||||
$(GUIDE_ADOC_FILES) \
|
||||
$(ASCIIDOC_EXTENSIONS) \
|
||||
$(NULL)
|
||||
|
||||
GUIDE_MAN_PAGES = \
|
||||
|
|
@ -150,10 +155,11 @@ GUIDE_ASCIIDOC_ARGS = \
|
|||
-a toclevels=3 \
|
||||
-a webfonts! \
|
||||
-b html5 \
|
||||
$(patsubst %,-r $(srcdir)/%,${ASCIIDOC_EXTENSIONS}) \
|
||||
$(NULL)
|
||||
|
||||
DOC_PROC = mkdir -p doc/output/html/ && $(ASCIIDOCTOR) $(GUIDE_ASCIIDOC_ARGS) -a asciidoctor -o $@ $<
|
||||
render-docs: $(GUIDE_ADOC_FILES) $(GUIDE_MAIN_ADOC_FILE) $(MAN_ADOC_FILES)
|
||||
render-docs: $(ASCIIDOC_EXTENSIONS) $(GUIDE_ADOC_FILES) $(GUIDE_MAIN_ADOC_FILE) $(MAN_ADOC_FILES)
|
||||
mkdir -p doc/output/html/
|
||||
$(ASCIIDOCTOR) $(GUIDE_ASCIIDOC_ARGS) -a asciidoctor -D doc/output/html $(GUIDE_ADOC_FILES) $(MAN_ADOC_FILES)
|
||||
$(ASCIIDOCTOR) $(GUIDE_ASCIIDOC_ARGS) -a asciidoctor -o doc/output/html/index.html $(GUIDE_MAIN_ADOC_FILE)
|
||||
|
|
|
|||
|
|
@ -22,6 +22,14 @@ MANPAGES = \
|
|||
|
||||
if ENABLE_DOC
|
||||
|
||||
ASCIIDOC_EXTENSIONS = \
|
||||
doc/extensions/man-inline-macro.rb \
|
||||
$(NULL)
|
||||
|
||||
dist_noinst_DATA += \
|
||||
$(ASCIIDOC_EXTENSIONS) \
|
||||
$(NULL)
|
||||
|
||||
man_MANS += \
|
||||
$(MANPAGES) \
|
||||
$(NULL)
|
||||
|
|
@ -34,6 +42,7 @@ 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 $@ $<
|
||||
|
|
|
|||
11
doc/extensions/README.adoc
Normal file
11
doc/extensions/README.adoc
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
= Antora & AsciiDoctor Extensions
|
||||
|
||||
We need to support AsciiDoctor for generating local HTML pages as well as manpages while packaging to various distros.
|
||||
|
||||
But as we also publish using Antora, there might be small differences that we need to address either on the AsciiDoctor or Antora-side, or even both.
|
||||
|
||||
== man-inline-macro.rb
|
||||
|
||||
An AsciiDoctor extension that converts manpages like cockpit(1) to links `man:cockpit[1]` for HTML pages and boldened `*cockpit(1)*` for manpages.
|
||||
|
||||
These manpage macros do not work for the local editing of Antora within the Cockpit repo. Within the Cockpit Docs Antora repo there is an AsciiDoctor.js extension `man-inline-replace.js` that replaces `man:` links. Future improvement here could be to move the extension to the cockpit repo and fetch it from the cockpit-docs repo, but that would require more work and doesn't provide much value at the moment.
|
||||
40
doc/extensions/man-inline-macro.rb
Normal file
40
doc/extensions/man-inline-macro.rb
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
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
|
||||
|
|
@ -148,7 +148,7 @@ cp /etc/ipa/ca.crt /etc/sssd/pki/sssd_auth_ca_db.pem
|
|||
....
|
||||
|
||||
Certificate authentication needs to be enabled in
|
||||
link:./cockpit.conf.5.html[cockpit.conf] explicitly:
|
||||
man:cockpit.conf[5] explicitly:
|
||||
|
||||
....
|
||||
[WebService]
|
||||
|
|
@ -174,7 +174,7 @@ action = none
|
|||
|
||||
When using certificate authentication, all requests with a particular
|
||||
certificate will be handled by a separate and isolated instance of the
|
||||
link:./cockpit-ws.8.html[cockpit-ws] web server. This protects against
|
||||
man:cockpit-ws[8] web server. This protects against
|
||||
possible vulnerabilities in the web server and prevents an attacker from
|
||||
impersonating another user. However, this introduces a potential Denial
|
||||
of Service: Some remote attacker could create a large number of
|
||||
|
|
|
|||
|
|
@ -323,7 +323,7 @@ a script tag. Alternatively you can use an javascript loader.
|
|||
[[package-bridges]]
|
||||
== Bridges for specific tasks
|
||||
|
||||
On the server side the link:#cockpit-bridge.1[`+cockpit-bridge+`]
|
||||
On the server side the man:cockpit-bridge[1]
|
||||
connects to various system APIs that the front end UI requests it to.
|
||||
There are additional bridges for specific tasks that the main
|
||||
`+cockpit-bridge+` cannot handle, such as using the PCP C library API.
|
||||
|
|
|
|||
|
|
@ -43,4 +43,4 @@ include::../partials/author.adoc[]
|
|||
|
||||
== See also
|
||||
|
||||
*cockpit-ws(8)*
|
||||
man:cockpit-ws[8]
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ cockpit-desktop - Cockpit Desktop integration
|
|||
The *cockpit-desktop* program provides secure access to Cockpit pages
|
||||
in an already running desktop session. It starts a web server
|
||||
(*cockpit-ws*) and a web browser in an isolated network namespace, and
|
||||
a *cockpit-bridge(1)* in the running user session.
|
||||
a man:cockpit-bridge[1] in the running user session.
|
||||
|
||||
This avoids having to log into Cockpit, and having to enable
|
||||
*cockpit.socket* system-wide. The network isolation ensures that no
|
||||
|
|
@ -51,4 +51,4 @@ include::../partials/author.adoc[]
|
|||
|
||||
== See also
|
||||
|
||||
*cockpit-ws(8)*, *cockpit-bridge(1)*
|
||||
man:cockpit-ws[8], man:cockpit-bridge[1]
|
||||
|
|
|
|||
|
|
@ -11,21 +11,21 @@ cockpit-tls - TLS proxy for Cockpit web service
|
|||
== Description
|
||||
|
||||
The *cockpit-tls* program is a TLS terminating HTTP proxy for
|
||||
*cockpit-ws(8)*. It manages a set of isolated cockpit-ws instances,
|
||||
man:cockpit-ws[8]. It manages a set of isolated cockpit-ws instances,
|
||||
one per TLS client certificate, plus one for TLS without a client
|
||||
certificate, and one for unencrypted HTTP. With that, one session cannot
|
||||
tamper with another one through possible security vulnerability
|
||||
exploits.
|
||||
|
||||
Users or administrators should never need to start this program as it
|
||||
automatically started by *systemd(1)* via socket activation.
|
||||
automatically started by man:systemd[1] via socket activation.
|
||||
|
||||
== Transport security
|
||||
|
||||
To specify the TLS certificate the web service should use, simply drop a
|
||||
file with the extension *.cert* in the */etc/cockpit/ws-certs.d*
|
||||
directory, or below *$XDG_CONFIG_DIRS* if set (see
|
||||
link:./cockpit.conf.5.html[cockpit.conf]). If there are multiple files
|
||||
man:cockpit.conf[5]). If there are multiple files
|
||||
in this directory, then the highest priority one is chosen after
|
||||
sorting.
|
||||
|
||||
|
|
@ -98,7 +98,7 @@ client certificates. This variable is normally set by the
|
|||
In addition, *cockpit-tls* will use the *XDG_CONFIG_DIRS*
|
||||
environment variable from the
|
||||
https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG
|
||||
basedir spec] to find its certificates and the *cockpit.conf(5)*
|
||||
basedir spec] to find its certificates and the man:cockpit.conf[5]
|
||||
configuration file.
|
||||
|
||||
== Bugs
|
||||
|
|
@ -111,4 +111,4 @@ include::../partials/author.adoc[]
|
|||
|
||||
== See also
|
||||
|
||||
*cockpit-ws(8)* , *cockpit.conf(5)* , *systemd(1)*
|
||||
man:cockpit-ws[8] , man:cockpit.conf[5] , man:systemd[1]
|
||||
|
|
|
|||
|
|
@ -13,11 +13,11 @@ cockpit-ws - Cockpit web service
|
|||
|
||||
The *cockpit-ws* program is the web service component used for
|
||||
communication between the browser application and various configuration
|
||||
tools and services like *cockpit-bridge(1)*.
|
||||
tools and services like man:cockpit-bridge[1].
|
||||
|
||||
Users or administrators should never need to start this program as it
|
||||
automatically started by *systemd(1)* on bootup, through
|
||||
*cockpit-tls(8)*.
|
||||
automatically started by man:systemd[1] on bootup, through
|
||||
man:cockpit-tls[8].
|
||||
|
||||
== Transport security
|
||||
|
||||
|
|
@ -25,11 +25,11 @@ automatically started by *systemd(1)* on bootup, through
|
|||
terminating proxy, and only deals with unencrypted HTTP by itself. But
|
||||
for backwards compatibility it can also handle TLS connections by itself
|
||||
when being run directly. For details how to configure certificates,
|
||||
please refer to the *cockpit-tls(8)* documentation.
|
||||
please refer to the man:cockpit-tls[8] documentation.
|
||||
|
||||
== Timeout
|
||||
|
||||
When started via *systemd(1)* then *cockpit-ws* will exit after 90
|
||||
When started via man:systemd[1] then *cockpit-ws* will exit after 90
|
||||
seconds if nobody logs in, or after the last user is disconnected.
|
||||
|
||||
== Options
|
||||
|
|
@ -54,7 +54,7 @@ seconds if nobody logs in, or after the last user is disconnected.
|
|||
that does the TLS termination. Then Cockpit puts https:// URLs into
|
||||
the default *Content-Security-Policy*, and accepts only https://
|
||||
origins, instead of http: ones by default. However, if *Origins* is
|
||||
set in the *cockpit.conf(5)* configuration file, it will override
|
||||
set in the man:cockpit.conf[5] configuration file, it will override
|
||||
this default.
|
||||
*--local-ssh*::
|
||||
Normally *cockpit-ws* uses *cockpit-session* and PAM to
|
||||
|
|
@ -84,7 +84,7 @@ can access the session!
|
|||
The *cockpit-ws* process will use the *XDG_CONFIG_DIRS* environment
|
||||
variable from the
|
||||
https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG
|
||||
basedir spec] to find its *cockpit.conf(5)* configuration file.
|
||||
basedir spec] to find its man:cockpit.conf[5] configuration file.
|
||||
|
||||
In addition the *XDG_DATA_DIRS* environment variable from the
|
||||
https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG
|
||||
|
|
@ -101,4 +101,4 @@ include::../partials/author.adoc[]
|
|||
|
||||
== See also
|
||||
|
||||
*cockpit-tls(8)* , *cockpit.conf(5)* , *systemd(1)*
|
||||
man:cockpit-tls[8] , man:cockpit.conf[5] , man:systemd[1]
|
||||
|
|
|
|||
|
|
@ -32,4 +32,4 @@ include::../partials/author.adoc[]
|
|||
|
||||
== See also
|
||||
|
||||
*cockpit-tls(8)* , *cockpit.bridge(1)* , *systemd(1)*, *https://docs.cockpit-project.org/cockpit-guide/latest[Cockpit guide]*
|
||||
man:cockpit-tls[8] , man:cockpit-bridge[1] , man:systemd[1], *https://docs.cockpit-project.org/cockpit-guide/latest[Cockpit guide]*
|
||||
|
|
|
|||
|
|
@ -193,4 +193,4 @@ include::../partials/author.adoc[]
|
|||
|
||||
== See also
|
||||
|
||||
*cockpit-ws(8)*, *cockpit-tls(8)*
|
||||
man:cockpit-ws[8], man:cockpit-tls[8]
|
||||
|
|
|
|||
Loading…
Reference in a new issue