Re: [PATCH] termios.3: SPARC architecture has 4 different Bnnn constants

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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/