svn commit: r317681 - head/share/man/man7

[Bruce Evans]

On Tue, 2 May 2017, Konstantin Belousov wrote:

> Log:
>  Document time_t size.
>
> Modified: head/share/man/man7/arch.7
> ==============================================================================
> --- head/share/man/man7/arch.7	Tue May  2 14:52:28 2017	(r317680)
> +++ head/share/man/man7/arch.7	Tue May  2 14:52:35 2017	(r317681)
> @@ -47,27 +47,27 @@ On all supported architectures,
> .It float Ta 4
> .It double Ta 8
> .El
> -.Bl -column -offset indent "Sy Architecture" "Sy sizeof(void *)" "Sy sizeof(long double)"
> -.It Sy Architecture Ta Sy sizeof(void *) Ta Sy sizeof(long double)
> ...
> +.Bl -column -offset indent "Sy Architecture" "Sy sizeof(void *)" "Sy sizeof(long double)" "Sy sizeof(time_t)"
> +.It Sy Architecture Ta Sy sizeof(void *) Ta Sy sizeof(long double) Ta Sy sizeof(time_t)
> +.It amd64       Ta 8 Ta 16 Ta 8
> +.It arm         Ta 4 Ta  8 Ta 8

Verbose types mess up the formatting of man pages too.

The header is obviously too long.  -current man misformats it to 91 columns
on 80-column terminals.  FreeBSD-5 man respects COLUMNS, but mangles the
header more completely to do this (1).

-current man can't handle macros like "Sy" with -width or some other
things including the things used above.  This causes it to produce
excessive column spacing.  The formatting is bad enough without this
(verbose headers but all columns except "Architecture" have only 1-2
digits).  -current man just considers "Sy " as literal and increases
the column spacing by 3, giving a spacing of 7 columns instead of 4,
where we really want a negative number but 2 would work OK.

Also, these Sy's have syntax errors.  They really are literals, since
they are not preceded by a dot.  With -current man, dots would unimprove
the formatting further by producing an extra column for each dot.
Perhaps that is why it is already left out (it might break other lists).
The syntax is something like ".Sy ... Architecture" where other macros
in "..." don't need (and shouldn't have?) dots.

Removing all 4 Sy's only reduces the column widths by 3*3, so the total
width to 82.  There is a different problem before the first collumn.
The Sy's are already not present in the previous -column directive,
and this might what causes different leading indentation for the
previous list.  But I didn't touch the Sy's in the later -column
directions, and all the following first columns line up with this one.

(1) gnu man/groff splits the long line in the middle of 'long double',
long before the new problem with time_t.  Before that, it produces the
same wrong separation of 7 columns.  It then prints a long line, with
87 blanks to misformat "double)" 1 line and 7 columns into the next
(in the middle of nowhere under "Architecture"), then a further 7 columns
to sizeof(time_t) in the middle of nowhere.  It prints a diagnostic
about not being able to split the long line.

Gnu man/groff does understand .Sy, but treats Sy as literal.  Changing the
Sy's to .Sy's doesn't work any better than removing them in this list,
but it improves all the other lists.

The formatting for the first list can be fixed by changing '-indent' in
it to 'indent' to match the other list.  This [-]indent controls
indentation in ways that I don't understand, but experiment shows that
the '-' in it gives an unwanted extra column of indentation, and adding
more minus signs gives more indentation.  The minus sign is only used
for the first list.

We really want outdentation.  I tried ++indent for that, but it gave
the same indentation as --indent.

Bruce