newgrp.1.adoc: use bold font for command name in synopsis
PATCH 1/4 newgrp.1.adoc: use bold font for command name in synopsis
newgrp.1.adoc is our only man page that doesn't use bold font for the command name in the synopsis. Fix that.
--- login-utils/newgrp.1.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
login-utils/newgrp.1.adoc +1 -1
@@ -14,7 +14,7 @@ newgrp - log in to a new group == SYNOPSIS -newgrp [_group_] +*newgrp* [_group_] == DESCRIPTION
Signature · 1 line
2.35.1.301.gcdacdcff8b.dirty
PATCH 2/4 mount.8.adoc: use bold font for literal text in synopsis
In a synopsis, *bold* text means "type exactly as shown" (see man(1)). mount.8.adoc has *--make*-[*shared*|...] which is weird because the middle dash is not in bold even though it's meant to be typed literally. Make it bold like the surrounding text.
--- sys-utils/mount.8.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
sys-utils/mount.8.adoc +1 -1
@@ -55,7 +55,7 @@ mount - mount a filesystem *mount* *--bind*|*--rbind*|*--move* _olddir newdir_ -*mount* *--make*-[*shared*|*slave*|*private*|*unbindable*|*rshared*|*rslave*|*rprivate*|*runbindable*] _mountpoint_ +*mount* *--make-*[*shared*|*slave*|*private*|*unbindable*|*rshared*|*rslave*|*rprivate*|*runbindable*] _mountpoint_ == DESCRIPTION
Signature · 1 line
2.35.1.301.gcdacdcff8b.dirty
PATCH 3/4 kill.1.adoc: clarify syntax of -SIG argument in synopsis
In reply to Johannes Altmanningerkill.1.adoc has this synopsis line
*kill* [-signal|*-s* _signal_]
For "-signal", the leading "-" should be typed literally, and the "signal" suffix should be replaced by a signal name/number. This means that according to GNU man(1), the "-" should render in bold font whereas the "signal" placeholder should use italic (which terminals often render with underscores).
Make it so. Use two askerisks because one is not enough for sub-word markup [*].
[*] https://docs.asciidoctor.org/asciidoc/latest/text/#unconstrained
--- misc-utils/kill.1.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
misc-utils/kill.1.adoc +1 -1
@@ -17,7 +17,7 @@ kill - terminate a process == SYNOPSIS -*kill* [-signal|*-s* _signal_|*-p*] [*-q* _value_] [*-a*] [*--timeout* _milliseconds_ _signal_] [*--*] _pid_|_name_... +*kill* [**-**_signal_|*-s* _signal_|*-p*] [*-q* _value_] [*-a*] [*--timeout* _milliseconds_ _signal_] [*--*] _pid_|_name_... *kill* *-l* [_number_] | *-L*
Signature · 1 line
2.35.1.301.gcdacdcff8b.dirty
PATCH 4/4 getopt.1.adoc: render synopsis rules on separate lines
In reply to Johannes AltmanningerAsciiDoc ignores single line breaks, so the synopsis of
*getopt* _variant1_ *getopt* _variant2_
will render as one line in the manpage.
Fix this by adding a blank line in between two rules, like we do elsewhere. This means that the manpage also has blank lines.
*getopt* _variant1_ *getopt* _variant2_
Alternative solution: we could avoid the blank lines like below, but that'd be inconsistent with our other manpages.
*getopt* _variant1_ + *getopt* _variant2_ +
or, equivalently, use the verse[*] directive
[verse] *getopt* _variant1_ *getopt* _variant2_
[*]: https://docs.asciidoctor.org/asciidoc/latest/blocks/verses/
--- misc-utils/getopt.1.adoc | 2 ++ 1 file changed, 2 insertions(+)
misc-utils/getopt.1.adoc +2 -0
@@ -14,7 +14,9 @@ getopt - parse command options (enhanced) == SYNOPSIS *getopt* _optstring_ _parameters_ + *getopt* [options] [*--*] _optstring_ _parameters_ + *getopt* [options] *-o*|*--options* _optstring_ [options] [*--*] _parameters_ == DESCRIPTION
Signature · 1 line
2.35.1.301.gcdacdcff8b.dirty
Re: [PATCH 4/4] getopt.1.adoc: render synopsis rules on separate lines
Hello Johannes,
Am Mo., 7. Feb. 2022 um 16:45 Uhr schrieb Johannes Altmanninger <[email protected]>:
Quoted 15 lines
AsciiDoc ignores single line breaks, so the synopsis of
*getopt* _variant1_ *getopt* _variant2_will render as one line in the manpage.
Fix this by adding a blank line in between two rules, like we do elsewhere. This means that the manpage also has blank lines.
*getopt* _variant1_ *getopt* _variant2_
Quoted 6 lines
Alternative solution: we could avoid the blank lines like below, but that'd be inconsistent with our other manpages.
*getopt* _variant1_ + *getopt* _variant2_ +
This would be possible, but we need in any case a solution which can be parsed by Po4a to generate a translation template and write the gettext messages properly to the translated man page. With the appended plus sign, Po4a generates the following gettext message:
#. type: Plain text
#: ../misc-utils/getopt.1.adoc:19
#, no-wrap
msgid ""
"*getopt* _optstring_ _parameters_ +\n"
"*getopt* [options] [*--*] _optstring_ _parameters_ +\n" "*getopt* [options] *-o*|*--options* _optstring_ [options] [*--*] _parameters_\n"
msgstr ""
Even in case translators recognize the plus sign correctly, Po4a writes it indeed back to the translated *.adoc file, but in a way that Asciidoctor parses it as an arbitrary plus sign within the text – and concatenates the lines anyway, now with a few more plus signs …
Quoted 6 lines
or, equivalently, use the verse[*] directive
[verse] *getopt* _variant1_ *getopt* _variant2_
This is IMHO the best solution. It looks good in the translation template, and it renders properly in the translated man page. If I find some time next days, I will create a global patch for all affected man pages – not only for the "SYNOPSIS" sections, this "[verse]" thing seems to be also perfectly usable for multiline "AUTHORS" sections.
Thanks for reviewing the man pages!
Best Regards,
Mario
Karel Zak
maintainerQuoted 2 lines · Johannes Altmanninger
login-utils/newgrp.1.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Applied (all 4 patches), thanks!
Karel
Signature · 2 lines
Karel Zak <[email protected]> http://karelzak.blogspot.com