Re: [PATCH v5 2/2] sockaddr.3type: ffix

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 2798 bytes --]

[replying just to Alex and the lists]

Hi Alex,

At 2022-07-30T01:01:09+0200, Alejandro Colomar wrote:
> Format structures with tbl(1) to improve alignment in
> proportional-width font text.
> 
> I also reordered the types in the SYNOPSIS, to be consistent with
> C syntax.
> 
> Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> Cc: Heinz-Jürgen Oertel <hj.oertel@t-online.de>
> Cc: Ralph Corderoy <ralph@inputplus.co.uk>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
> 
> This page clearly shows that using tabs would be hard.
> 
> Although having different alignment for every structure doesn't
> convince me...

You can resolve that.  Simply choose column widths that are large enough
for the widest data types and identifiers appearing in the page, and use
the `w` modifier in each table to impose that width on the relevant
columns.

At a glace, these look like plausible candidates.

> -.BR "    struct in6_addr sin6_addr;" "      /* IPv6 address */"
> -.BR "    uint32_t        sin6_scope_id;" "  /* Set of interfaces for a scope */"

"struct in6_addr" is 15 characters wide; in typographer-speak, call that
15 ens, and in roff(7) lands "15n".  "sin6_scope_id" is 13n.

So your table formats for this page would look like this.

lBW(15n)2 lBW(13n)2 l1 lX.

These explicit measurements are not guaranteed to be perfect; they may
leave excess space or even be too small in the unlikely event you have
to deal with data types or identifiers that look like "MWMWMWMWMWM".

On the bright side I can't think of how they could go wrong in
terminals.  And you can, of course, spend as much time time as you care
to tuning them for typesetting devices.

But these widths will have to be manually maintained, and in multiple
places at that.  (Of course, this only applies if a page documents more
than one struct or union type _and_ uses more than one table _and_ you
want the columns to align across those tables.)

Like I said on the groff list, tbl(1) is heavy machinery.  And beautiful
typography spreads its sublime wings when proportional typefaces get
involved.  There are good roffish tricks for avoiding some of these
problems--they involve using the `\w` escape sequence to measure things,
and storing the results in registers--but unfortunately they are
unlikely to work well, or at all, with mandoc(1) or other non-roff
formatters.

But, people thought they weren't giving up anything important when, 20
years ago, they decided they wanted to wanted to parse man pages into
XML or HTML without having to implement a roff formatter.  man(7) pages
were "almost" simple enough...

So if you want me to resurrect that tab stop-computing macro idea, let
me know.  ;-)

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]