From: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
To: util-linux@vger.kernel.org
Subject: [PATCH] doc: howto-man-page.txt: Use font macros instead of font escapes
Date: Mon, 16 Dec 2019 22:20:32 +0000 [thread overview]
Message-ID: <20191216222032.GA25430@rhi.hi.is> (raw)
Use font macros instead of font escapes (\f[BIPR]).
The escape '\c' ("connect to next input text")
is used to join the output of two macros without a space character.
This is similar to the '\' escape at the end of a line.
Font escapes make the text more difficult to read.
###
Changes based on:
Use a macro to change to the italic font,
instead of \fI [1], if possible.
The macros have the italic corrections,
but "\c" removes the "\/" part.
Or
add the italic corrections.
[1] man-pages(7) [Debian package "manpages"]
###
Change a HYPHEN-MINUS (code 0x55, 2D) to a minus (\-), if in front of a
1) name for an option
2) negative number to be printed.
###
Wrong distance between sentences or protect the indicator.
a) Separate the sentences and subordinate clauses;
each begins on a new line.
See man-pages(7) [package "manpages"] and "info groff".
Or
b) Adjust space between sentences (two spaces),
c) or protect the indicator by adding "\&" after it.
The "indicator" is an "end-of-sentence character" (.!?).
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
---
Documentation/howto-man-page.txt | 28 ++++++++++++++++++----------
1 file changed, 18 insertions(+), 10 deletions(-)
diff --git a/Documentation/howto-man-page.txt b/Documentation/howto-man-page.txt
index 55734af91..f2b352dac 100644
--- a/Documentation/howto-man-page.txt
+++ b/Documentation/howto-man-page.txt
@@ -30,10 +30,13 @@ Each manual page needs some sort of description of the command.
Write such here.
.SH OPTIONS
.TP
-\fB\-n\fR, \fB\-\-no\-argument\fR
+.BR \-n ,\ \-\-no\-argument
+.\" \fB\-n\fR, \fB\-\-no\-argument\fR
This option does not use an argument.
.TP
-\fB\-\-optional\fR[\fI=argument\fR]
+.BR \-\-optional [ =\c
+.IR argument ]
+.\" \fB\-\-optional\fR[\fI=argument\fR]
Tell in this description that the
.I argument
is optional, and what happens when it is or is not given. Notice that the word
@@ -59,18 +62,22 @@ to be the same, but in fact the former is two separate options while the
later will use
.B n
as option argument of
-.BR -o .
+.BR \-o .
So it is best to avoid short forms of optional options altogether.
.TP
-\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
+.BR \-r ,\ \-\-required\ \c
+.I argument
+.\"\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
Tell in this description that the
.I argument
is required.
.TP
-\fB\-V\fR, \fB\-\-version\fR
+.BR \-V ", " \-\-version
+.\"\fB\-V\fR, \fB\-\-version\fR
Display version information and exit.
.TP
-\fB\-h\fR, \fB\-\-help\fR
+.BR \-h ,\ \-\-help
+.\"\fB\-h\fR, \fB\-\-help\fR
Display help text and exit.
.SH NOTES
Tell details that users might need to know. For example, kernel feature or
@@ -105,7 +112,8 @@ one.
.\"
.PP
When in the source a new sentence begins somewhere midline, it should use a
-double space before its initial letter. This is done because \fBgroff\fR
+double space before its initial letter. This is done because
+.B groff
uses a double space after a sentence when this sentence ends at the end of
an input line and the next sentence begins on the next line.
Unless a double space is used before other sentence starts as well, the
@@ -139,10 +147,10 @@ Another file.
Write typical and/or clever use examples here. The below examples are stupid,
and you should never write them in a real man page.
.TP
-.B example -h
+.B example \-h
Output help screen.
.TP
-.B example -V
+.B example \-V
Output version information.
.SH "EXIT STATUS"
This section can be left out if the command has only two return values,
@@ -171,7 +179,7 @@ etc
.RE
.SH AUTHORS
.MT rjh@\:example.org
-Random J. Hacker
+Random J.\& Hacker
.ME
.br
.MT fred@\:example.com
--
2.24.0
next reply other threads:[~2019-12-16 22:20 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-12-16 22:20 Bjarni Ingi Gislason [this message]
2019-12-17 20:43 ` [PATCH] doc: howto-man-page.txt: Use font macros instead of font escapes J William Piggott
2020-01-02 0:17 ` Bjarni Ingi Gislason
2020-01-02 16:52 ` J William Piggott
2020-01-03 11:48 ` Karel Zak
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20191216222032.GA25430@rhi.hi.is \
--to=bjarniig@rhi.hi.is \
--cc=util-linux@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).