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

[Bruce Evans]

On Tue, 2 May 2017, Konstantin Belousov wrote:

> On Wed, May 03, 2017 at 04:41:52AM +1000, Bruce Evans wrote:
>> It would be good to mention that the type of time_t is signed somewhere.
>> There is a whole column for the signedess of char in another table.
>> Signedness can be given consisely using some markup like -8 or 8- for
>> signed.  The scale (often bytes or bits) could be given similarly.  E.g,
>> 8-B could mean signed 8 bits and 80.b could mean 80 bits floating pint.
>>
>> The Page Size table says "Page Sizes" redundantly in 1 column but doesn't
>> gives units, and depends on everyone knowing that 4K is real K and bytes.
> I added a note at the very beginning, saying that sizes are in bytes.
> For time_t, I added a short narration besides the table data.
>
>>
>> The Floating Point table already doesn't say "sizeof()" in the header but
> [omited, I do not want to change the scope of the fix]

OK.

Including corrections by ngie:

> diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7
> index 1ce397a303e..ad1abccc2e5 100644
> --- a/share/man/man7/arch.7
> +++ b/share/man/man7/arch.7
> @@ -37,6 +37,8 @@ Differences between CPU architectures and platforms supported by
> .Fx .
> .Pp

This .Pp gives misformatting (an extra blank line) when followed by .Ss.
Apparently, .Ss gives its own paragraph break.

> .Ss Type sizes
> +If not explicitely mentioned, sizes are in bytes.

"explicitly"

This should be moved higher, so that it applies to the "Page Size" section.
The first clause isn't needed, since there are no explicit mentions of
sizes not in bytes (there is only "80 bits" for some FP values which don't
claim to be sizes and aren't really sizes and should be changed to "64
bits" and claim to be precisions).

> +.Pp

Check the formatting after moving the addition higher.  There will be 2
very short paragraphs if you keep this .Pp.

> On all supported architectures,

The comma at the end of this should be a colon.

There is no corresponding period to delimit the end of any of the lists
except one sublist of "Predefined Macros" where the formatting of the
sublist is probably wrong to have this (it has separate sentences with
punctuation, unlike in all other tables).  This section correctly uses
colons.

> .Bl -column -offset -indent "long long" "Size"
> .It Sy Type Ta Sy Size
> @@ -47,8 +49,10 @@ 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)" "Sy sizeof(time_t)"
> -.It Sy Architecture Ta Sy sizeof(void *) Ta Sy sizeof(long double) Ta Sy sizeof(time_t)
> +.Pp
> +Machine-dependent type sizes:
> +.Bl -column -offset indent "Sy Architecture" "Sy void *" "Sy long double" "Sy time_t"
> +.It Sy Architecture Ta Sy void * Ta Sy long double Ta Sy time_t
> .It amd64       Ta 8 Ta 16 Ta 8
> .It arm         Ta 4 Ta  8 Ta 8
> .It armeb       Ta 4 Ta  8 Ta 8
> @@ -69,6 +73,9 @@ On all supported architectures,
> .It riscv       Ta 8 Ta 16 Ta 8
> .It sparc64     Ta 8 Ta 16 Ta 8
> .El
> +.Pp
> +.Sy time_t
> +is always signed, it is 64-bits everywere except on i386 and 32-bit powerpc.

Change "is always" to "On all supported arches" as elsewhere.

"everywhere"

"everywhere" is redundant.

The whole second clause is redundant.  Remove it.  Leave it to the reader
to notice that the table has more 8's than 4's, and where the 4's are.
This also fixes:
- bad grammar (comma splice).  In general, use separate sentences, since
   the rules for splicing clauses using commas and semicolons or avoiding
   these using a word are complicated, though I used splicing in this
   sentence to help make it so complicated (IIRC, "since" here is a
   splicing method with some technical name like "conjunctive adjective").
- inconsistent units (bytes in the table and bits here).

> .Ss Endianness and Char Signedness
> .Bl -column -offset indent "Sy Architecture" "Sy Endianness" "Sy char Signedness"
> .It Sy Architecture Ta Sy Endianness Ta Sy char Signedness

Bruce