[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 06/22: groff_man_style(7): Update "Notes" section.
From: |
G. Branden Robinson |
Subject: |
[groff] 06/22: groff_man_style(7): Update "Notes" section. |
Date: |
Mon, 2 Aug 2021 10:49:45 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 3013bdcb02f4f8c06eb692451aa00f8123ec5033
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Aug 1 15:44:13 2021 +1000
groff_man_style(7): Update "Notes" section.
* Add item: "Some ASCII characters look funny or copy and paste wrong."
* Make table headings read more grammatically if one imagines reading
the cell contents as part of them.
* Set metasyntactic macro arguments in italics.
* Add horizontal rules between each table row so that multi-line table
rows are not confusing.
* Replace '.IP "" 4n' -> '.TP 4n' example with a more salient one given
real-world specimens I've seen.
* Expand discussion of IP macro since it's so often used badly or
redundantly.
* Update example troff diagnostic to match its current wording.
* Add item: "Why do I need to keep retyping the indentation amount of a
series .IP paragraphs?" (Answer: you don't.)
* Fix style nit: add empty request after paragraph tags that are
sentences.
---
tmac/groff_man.7.man.in | 112 ++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 108 insertions(+), 4 deletions(-)
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 6e10dab..6cb33f4 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -3296,7 +3296,57 @@ Some tips on troubleshooting your man pages follow.
.
.
.TP
+\(bu Some ASCII characters look funny or copy and paste wrong.
+.
+On devices with large glyph repertoires,
+like UTF-8-capable terminals and PDF,
+several keyboard glyphs are mapped to code points outside the Unicode
+basic Latin range because that usually results in better typography in
+the general case.
+.
+When documenting GNU/Linux command or C language syntax,
+however,
+this translation is sometimes not desirable.
+.
+.TS
+c c
+rfCB lfCB.
+To get a \(lqliteral\(rq.\|.\|. .\|.\|.should be input.
+_
+\(aq \(rs(aq
+\- \(rs-
+\(rs \(rs(rs
+\(ha \(rs(ha
+\(ga \(rs(ga
+\(ti \(rs(ti
+_
+.TE
+.
+.
+.IP
+Additionally,
+if a neutral double quote (") is needed in a macro argument,
+you can use
+.B \(rs(dq
+to get it.
+.
+You should
+.I not
+use
+.B \(rs(aq
+for an ordinary apostrophe
+(as in \(lqcan't\(rq)
+or
+.B \(rs-
+for an ordinary hyphen
+(as in \(lqword-aligned\(rq).
+.
+Review subsection \(lqPortability\(rq above.
+.
+.
+.TP
\(bu Do I ever need to use an empty macro argument ("")?
+.
Probably not.
.
When this seems necessary,
@@ -3305,13 +3355,22 @@ often a shorter or clearer alternative is available.
.TS
c c
lfCB lfCB.
-Instead of.\|.\|. .\|.\|.do this.
+Instead of.\|.\|. .\|.\|.should be considered.
_
\&.TP \(dq\(dq .TP
-\&.BI \(dq\(dq italic-text bold-text .IB italic-text bold-text
+_
+\&.BI \(dq\(dq \fIitalic-text bold-text .IB \fIitalic-text bold-text
+_
\&.TH foo 1 \(dq\(dq \(dqfoo 1.2.3\(dq .TH foo 1 \
\f(CIyyyy\fP-\f(CImm\fP-\f(CIdd\fP \(dqfoo 1.2.3\(dq
-\&.IP \(dq\(dq 4n .TP 4n
+_
+\&.IP \(dq\(dq 4n .IP
+_
+\&.IP \(dq\(dq 4n .RS 4n
+\fIparagraph .P
+\fR.\|.\|. \fIparagraph
+\fR.\|.\|. .RE
+_
\&.B one two \(dq\(dq three .B one two three
.TE
.
@@ -3328,6 +3387,28 @@ a page maintainer will keep both up to date.
.
.
.IP
+.B .IP
+is sometimes ill-understood and misused,
+especially when no marker argument is supplied\(eman indentation
+argument is not required.
+.
+By setting an explicit indentation,
+you may be overriding the reader's preference as set with the
+.B \-rIN
+option.
+.
+If your page renders adequately without one,
+use the simpler form.
+.
+If you need to indent multiple (unmarked) paragraphs,
+consider an setting an indented region with
+.B .RS
+and
+.B .RE
+instead.
+.
+.
+.IP
In the last example,
the empty argument does have a subtly different effect than its
suggested replacement;
@@ -3343,6 +3424,7 @@ which can be overlooked in source and rendered forms.
.
.TP
.RB \(bu " .RS" " doesn't indent relative to my indented paragraph."
+.
The
.B .RS
macro sets the left margin;
@@ -3379,13 +3461,14 @@ values.
.TP
.RB \(bu " .RE" " doesn't move the inset back to the expected level."
.TQ
-\(bu warning: scaling indicator invalid in this context
+\(bu warning: scaling indicator invalid in context
.TQ
\(bu warning: number register \(aqan\-saved\-margin\c
.IR n "\(aq not defined"
.TQ
\(bu warning: number register \(aqan\-saved\-prevailing\-indent\c
.IR n "\(aq not defined"
+.
The
.B .RS
macro takes an
@@ -3426,6 +3509,27 @@ all relative insets are cleared and calls to
have no effect until
.B .RS
is used again.
+.
+.
+.TP
+\(bu Do I need to keep typing the indent in a series of \c
+.BR .IP " calls?"
+.
+You don't need to if you don't want to change the indentation.
+.
+Review subsection \(lqHorizontal and vertical spacing\(rq above.
+.
+.TS
+c c
+lfCB lfCB.
+Instead of.\|.\|. .\|.\|.should be considered.
+_
+\&.IP \(rs(bu 4n .IP \(rs(bu 4n
+\fIparagraph \fIparagraph
+\&.IP \(rs(bu 4n .IP \(rs(bu
+\fIanother-paragraph \fIanother-paragraph
+_
+.TE
_endif()dnl
.
.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 06/22: groff_man_style(7): Update "Notes" section.,
G. Branden Robinson <=