Hi, Branden!
On 8/4/21 8:14 AM, G. Branden Robinson wrote:
Hi, Alex!
At 2021-08-01T14:13:39+0200, Alejandro Colomar (man-pages) wrote:
On 8/1/21 1:22 PM, G. Branden Robinson wrote:
When I saw the patch, I had no idea what those .ft/.fi things do, and
guessed that they're correct based on existing context. I think your
replacement suggestion below is better.
The 'ft' request changes the font (or style), and accepts exactly the
same parameter as the \f font (style) escape.
The 'fi' request enables filling; 'nf' disables it.
Here's how I'd do that:
.P
On the SPARC architecture,
the following additional constants are supported.
.RS
.TP
.B B76800
.TQ
.B B153600
.TQ
.B B307200
.TQ
.B B614400
.RE
Why would I do it this way? I'm trying to keep the size of the
language we ask man page writers to learn as small as possible, and
I especially try to keep the number of *roff requests they have to
know as close to zero as possible. There are already two ways to
change fonts: through macros and escape sequences. Personally, I'd
like to protect casual man page writers from having to learn the
third. (And, again, outside of tbl(1) tables, I'd prefer they not
have to know the second [escapes].)
Can you please send a more detailed email about what the current
implementation does and how compatible is the solution and any
differences there may be (if any)?
Sure, I'll mark 'em up like assembly. I hope your mail reader uses a
monospaced/fixed-width font.
.fi \" enable filling[1] of text
.PP \" man(7) paragraphing macro; see groff_man(7)
On SPARC architecture \" text line
.PP \" man(7) paragraphing macro; see groff_man(7)
.nf \" disable filling of text
.ft B \" change font to style "B"
B76800 \" text line using literal tab
B153600 \" ditto
B307200 \" ditto
B614400 \" ditto
.ft P \" change font to "previous" selection
.fi \" enable filling[1] of text
Here's how I define filling in the groff Texinfo manual; many other
sources define it equivalently.
GNU 'troff' reads its input character by character, collecting words
as it goes, and fits as many words together on an output line as it
can--this is known as "filling". To GNU 'troff', a "word" is any
sequence of one or more characters that aren't spaces, tabs, or
newlines. Words are separated by spaces, tabs, newlines, or file
boundaries.(2) (*note Filling-Footnote-2::) To disable filling, see
*note Manipulating Filling and Adjustment::.
I try to avoid use of tab characters in man page sources, except to
separate columns in tbl(1) input. I prefer to use the relative inset
feature (.RS/.RE) because the default size of a relative inset is a
configurable parameter. (And if must be a certain value, it can be set
as the argument to the RS macro.)
.P \" man(7) paragraphing macro; see groff_man(7)
On the SPARC[...]
the following[...]
.RS \" begin relative inset
.TP \" begin tagged paragraph
.B B76800 \" set argument in bold style
.TQ \" declare additional paragraph tag
.B B153600 \" [repeat previous two lines]
.TQ \"
.B B307200 \"
.TQ \"
.B B614400 \"
.RE \" end relative inset.
Yes, I prefer this way.
I'm sorry I forgot to answer to this email. There may be others also...
If I forgot to address anything important, feel free to ping me :)
Cheers,
Alex
.RS and .RE are used with timidity by man page authors; I think it is
because they are ill-understood. It is certainly not because they are
new; like .B and .TP they date back to the original 1979 man(7)
implementation. Even .P is "new", dating to Unix System III in 1980.
.TQ is the real newcomer, introduced to groff in January 2007. Like
.TP, it's somewhat semantic.
I'd like to be able to fix that.
Let me know if I can shed more light on things.
Regards,
Branden
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
