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

[Konstantin Belousov]

On Wed, May 03, 2017 at 08:57:10PM +1000, Bruce Evans wrote:
> On Wed, 3 May 2017, Konstantin Belousov wrote:
> 
> > On Wed, May 03, 2017 at 04:19:08PM +1000, Bruce Evans wrote:
> >> On Tue, 2 May 2017, Konstantin Belousov wrote:
> >>> +.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.
> > Ok.
> >
> >>
> >> 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.
> > No, this is one of the important reasons why this narrative text added
> > at all.
> 
> Why?  You just added time_t to the table.  It needs to be described twice
> less than most types.
> 
> Now I don't like the indirection long -> sizeof(void *) in the first table.
> This is the only place where the size is not given as a literal.  There
> used to be space in the second table to give the size of long explicitly.
> Now the space is used for time_t.  It doesn't belong in the same table,
> since it is not a basic type.
> 
> Also, intptr_t and intmax_t are not in the tables.
> 
> > diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7
> > index 47a72a1986d..62781430329 100644
> > --- a/share/man/man7/arch.7
> > +++ b/share/man/man7/arch.7
> > @@ -36,8 +36,9 @@
> > Differences between CPU architectures and platforms supported by
> > .Fx .
> > .Pp
> > +If not explicitly mentioned, sizes are in bytes.
> 
> The first clause is redundant.  There are no explicit mentions of non-byte
> sizes.
> 
> > .Ss Type sizes
> > -On all supported architectures,
> > +On all supported architectures:
> 
> I see a further problem with this clause.  It is separated from the table
> that it applies to, by both indentation and a blank line, so it appears
> to apply to the second table also.
> 
> Later sections don't have a blank line where they reasonably could.  They
> start with a section header, then no blank line between that and the single
> table in the section.

Th discussion is now reduced to the opinions.  Do you have any further
objections due to factual mistakes or language errors in the proposed
patch ?  If not, I will commit it as is.
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

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

[Bruce Evans]

On Wed, 3 May 2017, Konstantin Belousov wrote:


On Wed, May 03, 2017 at 04:19:08PM +1000, Bruce Evans wrote:

On Tue, 2 May 2017, Konstantin Belousov wrote:

+.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.

Ok.



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.

No, this is one of the important reasons why this narrative text added
at all.


Why?  You just added time_t to the table.  It needs to be described twice
less than most types.

Now I don't like the indirection long -> sizeof(void *) in the first table.
This is the only place where the size is not given as a literal.  There
used to be space in the second table to give the size of long explicitly.
Now the space is used for time_t.  It doesn't belong in the same table,
since it is not a basic type.

Also, intptr_t and intmax_t are not in the tables.


diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7
index 47a72a1986d..62781430329 100644
--- a/share/man/man7/arch.7
+++ b/share/man/man7/arch.7
@@ -36,8 +36,9 @@
Differences between CPU architectures and platforms supported by
.Fx .
.Pp
+If not explicitly mentioned, sizes are in bytes.


The first clause is redundant.  There are no explicit mentions of non-byte
sizes.


.Ss Type sizes
-On all supported architectures,
+On all supported architectures:


I see a further problem with this clause.  It is separated from the table
that it applies to, by both indentation and a blank line, so it appears
to apply to the second table also.

Later sections don't have a blank line where they reasonably could.  They
start with a section header, then no blank line between that and the single
table in the section.

Bruce
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

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

[Konstantin Belousov]

On Wed, May 03, 2017 at 04:19:08PM +1000, Bruce Evans wrote:
> On Tue, 2 May 2017, Konstantin Belousov wrote:
> 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.
Ok, see the cumulative changes in the patch.

> 
> > On all supported architectures,
> 
> The comma at the end of this should be a colon.
Ok.

> > +.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.
Ok.

> 
> 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.
No, this is one of the important reasons why this narrative text added
at all.

> 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).
Ok.

diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7
index 47a72a1986d..62781430329 100644
--- a/share/man/man7/arch.7
+++ b/share/man/man7/arch.7
@@ -36,8 +36,9 @@
 Differences between CPU architectures and platforms supported by
 .Fx .
 .Pp
+If not explicitly mentioned, sizes are in bytes.
 .Ss Type sizes
-On all supported architectures,
+On all supported architectures:
 .Bl -column -offset -indent "long long" "Size"
 .It Sy Type Ta Sy Size
 .It short Ta 2
@@ -47,8 +48,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
@@ -70,6 +73,10 @@ 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 8 bytes on all supported architectures except i386 and 32-bit
+variants of powerpc.
 .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
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

Re: 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
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

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

[Ngie Cooper]

On Tue, May 2, 2017 at 12:45 PM, Konstantin Belousov
 wrote:

...

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

*explicitly

> +.Pp
>  On all supported architectures,
>  .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.

*everywhere

Thanks!
-Ngie
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

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

[Konstantin Belousov]

On Tue, May 02, 2017 at 02:36:24PM -0600, Ian Lepore wrote:
> On Tue, 2017-05-02 at 22:45 +0300, Konstantin Belousov wrote:
> > +is always signed, it is 64-bits everywere except on i386 and 32-bit
> > powerpc.
> 
> s/everywere/everywhere/

Fixed, thank you.

diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7
index 1ce397a303e..7cb05ea5271 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
 .Ss Type sizes
+If not explicitely mentioned, sizes are in bytes.
+.Pp
 On all supported architectures,
 .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 everywhere except on i386 and 32-bit powerpc.
 .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
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

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

[Ian Lepore]

On Tue, 2017-05-02 at 22:45 +0300, Konstantin Belousov wrote:
> +is always signed, it is 64-bits everywere except on i386 and 32-bit
> powerpc.

s/everywere/everywhere/

-- Ian

___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

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

[Konstantin Belousov]

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]

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
 .Ss Type sizes
+If not explicitely mentioned, sizes are in bytes.
+.Pp
 On all supported architectures,
 .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.
 .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
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

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

[Bruce Evans]

On Tue, 2 May 2017, Ed Maste wrote:


On 2 May 2017 at 12:35, Bruce Evans  wrote:


-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.


We discussed this in review D7261. I created arch.7 with ".Sy based on
an example from FreeBSD 10's mdoc(7). In D7261 I noted that there were
existing man pages with both ".Sy and "Sy .


All examples in at least FreeBSD-5's mdoc(7) use ".Sy" if it is the first
macro in a ``subsection''.  "Sy" is used more often but not as the first
macro.  Typically after '.It'.


Do you believe we should remove them altogether?


I think you mean "all of them in .Bl and similar macros".  I don't like
removing features that once worked.  Someone might be using them.  I
only noticed that I was using this one when it stopped working :-).

Bruce
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

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

[Bruce Evans]

On Tue, 2 May 2017, Konstantin Belousov wrote:


On Wed, May 03, 2017 at 02:35:17AM +1000, Bruce Evans wrote:

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).


I removed excessive sizeof(), which fixed width.


Hmm.  It leaves no mention of the scale.  More below.


diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7
index 1ce397a303e..73552d60209 100644
--- a/share/man/man7/arch.7
+++ b/share/man/man7/arch.7
@@ -47,8 +47,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-depended type's 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


Remove the buggy Sy's too.


.It amd64   Ta 8 Ta 16 Ta 8
.It arm Ta 4 Ta  8 Ta 8
.It armeb   Ta 4 Ta  8 Ta 8


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.

The Floating Point table already doesn't say "sizeof()" in the header but
gives a lot of details including units in some cases in the values.  The
long double in the table that you changed would be better placed in the
FP table, except it is short of space too.  The size info for a long double
on {amd64,i386} is in 2 tables in different incomplete forms:
- first table gives sizes {16, 12} with no mention of either sizes or units;
  these are object sizes in bytes
- second table gives values {80, 80} with no mention of sizes but mention of
  bits; these are the unpadded object/register sizes (not really available
  in C), expressed in different units.  This column in the table is mostly
  about the precision.  It says "double precision" in some places, "identical
  to double" in others, and "quad precision" for arm64 and sparc64 ("hard"
  for sparc64 is broken.  sparc64 can have either, but the default is soft
  since hard it is rearely or never implemented in hardware and is emulated
  even more slowly by doing it softly in trap handlers).  The 80's for
  amd64 and i386 are don't give the precision like the others.  The precision
  is 64 bits, and the 80-bit size is not really available in C.

  Better table entries would be something like

  (hard | soft), (8 | 10 | 12 | 16) bytes, (53 | 64 | 113) bit precision

  or for the longest case "hard, 16 bytes, 113 bit precision".  There is
  just enough space for this after removing the Sy's.  I don't like the
  duplication in this.  So better go back to "identical to double" where
  it applies, and apply it more.  Double is described as just hard or soft
  with no mention that the precision is always 53 bits (this should be
  in the ealier table of MI sizes).  Long double is then the same on some
  arches.

arm64 doesn't have an _fpmath.h for it in libc, so I don't see how it
can have the soft quad precision claimed in the table.  Similarly in
msun/arm/Makefile.inc.

riscv has an _fpmath.h stating quad precision, but isn't in any table in
arch.7.  This _fpmath.h seems quite buggy, with inconsistent commenting
out and macros not matching the struct, so I don't see how it can work
either.  msun/riscv/Makefile.inc claims 113 bits, and the struct is
consistent with this,  but the macros consistent with this are commented
out, so I don't see how it can compile.

aarch64 is like riscv except its _fpmath.h seems to be 

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

[Konstantin Belousov]

On Tue, May 02, 2017 at 02:04:09PM -0400, Ed Maste wrote:
> > +Machine-depended type's sizes:
> 
> Probably "Machine-dependent type sizes"

Sure.

diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7
index 1ce397a303e..f30dfbb8145 100644
--- a/share/man/man7/arch.7
+++ b/share/man/man7/arch.7
@@ -47,8 +47,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
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

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

[Ed Maste]

On 2 May 2017 at 12:35, Bruce Evans  wrote:
>
> -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.

We discussed this in review D7261. I created arch.7 with ".Sy based on
an example from FreeBSD 10's mdoc(7). In D7261 I noted that there were
existing man pages with both ".Sy and "Sy .

Do you believe we should remove them altogether?

On 2 May 2017 at 13:44, Konstantin Belousov  wrote:
>
> I removed excessive sizeof(), which fixed width.
>
> diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7
> index 1ce397a303e..73552d60209 100644
> --- a/share/man/man7/arch.7
> +++ b/share/man/man7/arch.7
> @@ -47,8 +47,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-depended type's sizes:

Probably "Machine-dependent type sizes"
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

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

[Konstantin Belousov]

On Wed, May 03, 2017 at 02:35:17AM +1000, Bruce Evans wrote:
> 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).

I removed excessive sizeof(), which fixed width.

diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7
index 1ce397a303e..73552d60209 100644
--- a/share/man/man7/arch.7
+++ b/share/man/man7/arch.7
@@ -47,8 +47,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-depended type's 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
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

Re: 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
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"

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

[Konstantin Belousov]

Author: kib
Date: Tue May  2 14:52:35 2017
New Revision: 317681
URL: https://svnweb.freebsd.org/changeset/base/317681

Log:
  Document time_t size.
  
  Reviewed by:  emaste, imp, vangyzen
  Sponsored by: The FreeBSD Foundation
  MFC after:1 week
  Differential revision:https://reviews.freebsd.org/D10568

Modified:
  head/share/man/man7/arch.7

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)
@@ -26,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 21, 2017
+.Dd May 2, 2017
 .Dt ARCH 7
 .Os
 .Sh NAME
@@ -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)
-.It amd64   Ta 8 Ta 16
-.It arm Ta 4 Ta  8
-.It armeb   Ta 4 Ta  8
-.It armv6   Ta 4 Ta  8
-.It arm64   Ta 8 Ta 16
-.It i386Ta 4 Ta 12
-.It mipsTa 4 Ta  8
-.It mipsel  Ta 4 Ta  8
-.It mipselhfTa 4 Ta  8
-.It mipshf  Ta 4 Ta  8
-.It mipsn32 Ta 4 Ta  8
-.It mips64  Ta 8 Ta  8
-.It mips64elTa 8 Ta  8
-.It mips64elhf  Ta 8 Ta  8
-.It mips64hfTa 8 Ta  8
-.It powerpc Ta 4 Ta  8
-.It powerpc64   Ta 8 Ta  8
-.It riscv   Ta 8 Ta 16
-.It sparc64 Ta 8 Ta 16
+.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
+.It armeb   Ta 4 Ta  8 Ta 8
+.It armv6   Ta 4 Ta  8 Ta 8
+.It arm64   Ta 8 Ta 16 Ta 8
+.It i386Ta 4 Ta 12 Ta 4
+.It mipsTa 4 Ta  8 Ta 8
+.It mipsel  Ta 4 Ta  8 Ta 8
+.It mipselhfTa 4 Ta  8 Ta 8
+.It mipshf  Ta 4 Ta  8 Ta 8
+.It mipsn32 Ta 4 Ta  8 Ta 8
+.It mips64  Ta 8 Ta  8 Ta 8
+.It mips64elTa 8 Ta  8 Ta 8
+.It mips64elhf  Ta 8 Ta  8 Ta 8
+.It mips64hfTa 8 Ta  8 Ta 8
+.It powerpc Ta 4 Ta  8 Ta 4
+.It powerpc64   Ta 8 Ta  8 Ta 8
+.It riscv   Ta 8 Ta 16 Ta 8
+.It sparc64 Ta 8 Ta 16 Ta 8
 .El
 .Ss Endianness and Char Signedness
 .Bl -column -offset indent "Sy Architecture" "Sy Endianness" "Sy char 
Signedness"
___
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"