[PATCH 1/4] 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

[Johannes Altmanninger]

newgrp.1.adoc is our only man page that doesn't use bold font for
the command name in the synopsis. Fix that.

Signed-off-by: Johannes Altmanninger <aclopte@gmail.com>
---
 login-utils/newgrp.1.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/login-utils/newgrp.1.adoc b/login-utils/newgrp.1.adoc
index b50b0d5f3..629078b5e 100644
--- a/login-utils/newgrp.1.adoc
+++ b/login-utils/newgrp.1.adoc
@@ -14,7 +14,7 @@ newgrp - log in to a new group
 
 == SYNOPSIS
 
-newgrp [_group_]
+*newgrp* [_group_]
 
 == DESCRIPTION
 
-- 
2.35.1.301.gcdacdcff8b.dirty

[PATCH 2/4] mount.8.adoc: use bold font for literal text in synopsis

[Johannes Altmanninger]

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.

Signed-off-by: Johannes Altmanninger <aclopte@gmail.com>
---
 sys-utils/mount.8.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc
index 6f4465d0d..714b8133d 100644
--- a/sys-utils/mount.8.adoc
+++ b/sys-utils/mount.8.adoc
@@ -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
 
-- 
2.35.1.301.gcdacdcff8b.dirty

[PATCH 3/4] kill.1.adoc: clarify syntax of -SIG argument in synopsis

[Johannes Altmanninger]

kill.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

Signed-off-by: Johannes Altmanninger <aclopte@gmail.com>
---
 misc-utils/kill.1.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/misc-utils/kill.1.adoc b/misc-utils/kill.1.adoc
index afdf345fd..4a6996a38 100644
--- a/misc-utils/kill.1.adoc
+++ b/misc-utils/kill.1.adoc
@@ -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*
 
-- 
2.35.1.301.gcdacdcff8b.dirty

[PATCH 4/4] getopt.1.adoc: render synopsis rules on separate lines

[Johannes Altmanninger]

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_

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/

Signed-off-by: Johannes Altmanninger <aclopte@gmail.com>
---
 misc-utils/getopt.1.adoc | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/misc-utils/getopt.1.adoc b/misc-utils/getopt.1.adoc
index 6cbdd5174..7a80b141e 100644
--- a/misc-utils/getopt.1.adoc
+++ b/misc-utils/getopt.1.adoc
@@ -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
-- 
2.35.1.301.gcdacdcff8b.dirty

Re: [PATCH 4/4] getopt.1.adoc: render synopsis rules on separate lines

[Mario Blättermann]

Hello Johannes,

Am Mo., 7. Feb. 2022 um 16:45 Uhr schrieb Johannes Altmanninger
<aclopte@gmail.com>:
>
> 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_
>
> 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 …

> 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

Re: [PATCH 1/4] newgrp.1.adoc: use bold font for command name in synopsis

[Karel Zak]

On Sun, Feb 06, 2022 at 07:11:55AM +0100, Johannes Altmanninger wrote:
>  login-utils/newgrp.1.adoc | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

 Applied (all 4 patches), thanks!

  Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com