man.7 tweaks

man.7 tweaks

[Jason McIntyre]

diff for some man.7 tweaks below. couple of questions:

*) openbsd doesn;t have a LIBRARY section. what is the best way to
reflect that? ingo?

*) (again ingo) how does this diff get committed?

*) unrelated, but i'm currently discussing the EXIT STATUS section with
daniel dickman:

	EXIT STATUS
        This section documents the command exit status for section
        1, 6, and 8 utilities.  Historically, this information was
        described in DIAGNOSTICS, a practise that is now discouraged.

says who? i mean, what leads you to believe this? i ask because openbsd
has no EXIT STATUS section, and both netbsd and freebsd have this in
their groff_man(7) pages:

	.Sh DIAGNOSTICS
        Diagnostic messages from a command should be placed in this
        section.  The `.Ex' macro may be used to generate text for
        use in the DIAGNOSTICS section for most section 1, 6 and
        8 commands; see Exit Status.

i'm trying to work out what the best way forward is.

jmc
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: man.7 tweaks

[Ingo Schwarze]

Hi Jason,

Jason McIntyre wrote on Sat, Jul 24, 2010 at 02:31:52PM +0059:

> diff for some man.7 tweaks below.

Thanks for working on this!

But you should indeed send the diff, it was not included.

> couple of questions:
> 
> *) openbsd doesn;t have a LIBRARY section. what is the best way to
> reflect that? ingo?

Hm, this applies to a couple of sections, and i haven't come to
a conclusion yet, either.

I think having an identical man(7) manual in all the supported
operating systems is a good thing.  At the same time, i think
the manual should not be blantantly wrong on any of them.
Can we, in some way, briefly address the differences, without
bloating the text too much?  Like in, e.g.,

  This section is used in FreeBSD and NetBSD, but not in OpenBSD.

A sentence of this kind makes it plain that there are OS-specific
conventions in this respect, without needing another sentence to
make that explicit.  If someone is using another system that is
not listed, it's obvious that s/he must look into it and find out.

> *) (again ingo) how does this diff get committed?

However you like.  If you feel you have enough OKs, just commit
to OpenBSD and Kristaps or myself will pick it up and commit it to
bsd.lv.  If you don't like that approach, you can also ask either
of us to commit to both repos in parallel.

> *) unrelated, but i'm currently discussing the EXIT STATUS section with
> daniel dickman:
> 
> 	EXIT STATUS
>         This section documents the command exit status for section
>         1, 6, and 8 utilities.  Historically, this information was
>         described in DIAGNOSTICS, a practise that is now discouraged.
> 
> says who? i mean, what leads you to believe this? i ask because openbsd
> has no EXIT STATUS section, and both netbsd and freebsd have this in
> their groff_man(7) pages:
> 
> 	.Sh DIAGNOSTICS
>         Diagnostic messages from a command should be placed in this
>         section.  The `.Ex' macro may be used to generate text for
>         use in the DIAGNOSTICS section for most section 1, 6 and
>         8 commands; see Exit Status.

Frankly, no idea...

> i'm trying to work out what the best way forward is.

Send the patch!  ;-)

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: man.7 tweaks

[Jason McIntyre]

On Sat, Jul 24, 2010 at 03:59:18PM +0200, Ingo Schwarze wrote:
> 
> > i'm trying to work out what the best way forward is.
> 
> Send the patch!  ;-)
> 

urgle!

Index: man.7
===================================================================
RCS file: /cvs/src/share/man/man7/man.7,v
retrieving revision 1.3
diff -u -r1.3 man.7
--- man.7	19 Jul 2010 23:06:29 -0000	1.3
+++ man.7	24 Jul 2010 13:23:14 -0000
@@ -111,7 +111,7 @@
 attribute is forgotten when entering or exiting a macro block.
 .Ss Whitespace
 Whitespace consists of the space character.
-In free-form lines, whitespace is preserved within a line; un-escaped
+In free-form lines, whitespace is preserved within a line; unescaped
 trailing spaces are stripped from input (unless in a literal context).
 Blank free-form lines, which may include spaces, are permitted and
 rendered as an empty line.
@@ -190,23 +190,25 @@
 which, if a unit is not provided, will instead interpret the string as
 literal text.
 .Ss Sentence Spacing
-When composing a manual, make sure that your sentences end at the end of
+When composing a manual, make sure that sentences end at the end of
 a line.
 By doing so, front-ends will be able to apply the proper amount of
 spacing after the end of sentence (unescaped) period, exclamation mark,
 or question mark followed by zero or more non-sentence closing
-delimiters (
-.Ns Sq \&) ,
+delimiters
+.Po
+.Sq \&) ,
 .Sq \&] ,
 .Sq \&' ,
-.Sq \&" ) .
+.Sq \&"
+.Pc .
 .Sh MANUAL STRUCTURE
 Each
 .Nm
-document must contain contains at least the
+document must contain the
 .Sx \&TH
 macro describing the document's section and title.
-It may occur anywhere in the document, although conventionally, it
+It may occur anywhere in the document, although conventionally it
 appears as the first macro.
 .Pp
 Beyond
@@ -291,10 +293,7 @@
 This is useful when implementing standard functions that may have side
 effects or notable algorithmic implications.
 .It Em RETURN VALUES
-This section is the dual of
-.Em EXIT STATUS ,
-which is used for commands.
-It documents the return values of functions in sections 2, 3, and 9.
+This section documents the return values of functions in sections 2, 3, and 9.
 .It Em ENVIRONMENT
 Documents any usages of environment variables, e.g.,
 .Xr environ 7 .
@@ -303,10 +302,8 @@
 It's helpful to document both the file name and a short description of how
 the file is used (created, modified, etc.).
 .It Em EXIT STATUS
-Command exit status for section 1, 6, and 8 manuals.
-This section is the dual of
-.Em RETURN VALUES ,
-which is used for functions.
+This section documents the command exit status for
+section 1, 6, and 8 utilities.
 Historically, this information was described in
 .Em DIAGNOSTICS ,
 a practise that is now discouraged.
@@ -314,7 +311,7 @@
 Example usages.
 This often contains snippets of well-formed,
 well-tested invocations.
-Make doubly sure that your examples work properly!
+Make sure that examples work properly!
 .It Em DIAGNOSTICS
 Documents error conditions.
 This is most useful in section 4 manuals.
@@ -351,13 +348,13 @@
 Common misuses and misunderstandings should be explained
 in this section.
 .It Em BUGS
-Known bugs, limitations and work-arounds should be described
+Known bugs, limitations, and work-arounds should be described
 in this section.
 .It Em SECURITY CONSIDERATIONS
 Documents any security precautions that operators should consider.
 .El
 .Sh MACRO SYNTAX
-Macros are one to three three characters in length and begin with a
+Macros are one to three characters in length and begin with a
 control character,
 .Sq \&. ,
 at the beginning of the line.
@@ -444,8 +441,8 @@
 .Nm
 manuals.
 .Ss Block Macros
-Block macros are comprised of a head and body.
-Like for in-line macros, the head is scoped to the current line and, in
+Block macros comprise a head and body.
+As with in-line macros, the head is scoped to the current line and, in
 one circumstance, the next line (the next-line stipulations as in
 .Sx Line Macros
 apply here as well).
@@ -602,8 +599,8 @@
 and
 .Sx \&r .
 .Ss \&IB
-Text is rendered alternately in italics and bold face.  Whitespace
-between arguments is omitted in output.
+Text is rendered alternately in italics and bold face.
+Whitespace between arguments is omitted in output.
 .Pp
 See
 .Sx \&BI
@@ -626,7 +623,7 @@
 The
 .Cm width
 argument defines the width of the left margin and is defined by
-.Sx Scaling Widths ,
+.Sx Scaling Widths .
 It's saved for later paragraph left-margins; if unspecified, the saved or
 default width is used.
 .Pp
@@ -943,7 +940,7 @@
 The stand-alone implementation that is part of the
 .Xr mandoc 1
 utility written by Kristaps Dzonsons appeared in
-.Ox 4.6.
+.Ox 4.6 .
 .Sh AUTHORS
 This
 .Nm
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: man.7 tweaks

[Jason McIntyre]

On Sat, Jul 24, 2010 at 03:59:18PM +0200, Ingo Schwarze wrote:
> > 
> > *) openbsd doesn;t have a LIBRARY section. what is the best way to
> > reflect that? ingo?
> 
> Hm, this applies to a couple of sections, and i haven't come to
> a conclusion yet, either.
> 
> I think having an identical man(7) manual in all the supported
> operating systems is a good thing.  At the same time, i think
> the manual should not be blantantly wrong on any of them.
> Can we, in some way, briefly address the differences, without
> bloating the text too much?  Like in, e.g.,
> 
>   This section is used in FreeBSD and NetBSD, but not in OpenBSD.
> 
> A sentence of this kind makes it plain that there are OS-specific
> conventions in this respect, without needing another sentence to
> make that explicit.  If someone is using another system that is
> not listed, it's obvious that s/he must look into it and find out.
> 

i guess the choices are either have different pages for different
systems (a pain to keep up to date but more accurate, kind of) or note
os differences within the page.

some more differences (at least between netbsd and open):

- man pages sections (as discussed)
- supported archs
- page suffixes maybe (think .3p)
- Dt (openbsd uses $mdocdate$)
- \*[Gt vs. \*(Gt
- rcsid

> > *) (again ingo) how does this diff get committed?
> 
> However you like.  If you feel you have enough OKs, just commit
> to OpenBSD and Kristaps or myself will pick it up and commit it to
> bsd.lv.  If you don't like that approach, you can also ask either
> of us to commit to both repos in parallel.
> 

so i will leave you guys to commit it, if it gets approved.

jmc
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: man.7 tweaks

[Ingo Schwarze]

This is all ok schwarze@.

Kristaps, if you like it, go ahead and commit to both repositories.

Jason McIntyre wrote on Sat, Jul 24, 2010 at 03:50:39PM +0059:

> Index: man.7
> ===================================================================
> RCS file: /cvs/src/share/man/man7/man.7,v
> retrieving revision 1.3
> diff -u -r1.3 man.7
> --- man.7	19 Jul 2010 23:06:29 -0000	1.3
> +++ man.7	24 Jul 2010 13:23:14 -0000
> @@ -111,7 +111,7 @@
>  attribute is forgotten when entering or exiting a macro block.
>  .Ss Whitespace
>  Whitespace consists of the space character.
> -In free-form lines, whitespace is preserved within a line; un-escaped
> +In free-form lines, whitespace is preserved within a line; unescaped
>  trailing spaces are stripped from input (unless in a literal context).
>  Blank free-form lines, which may include spaces, are permitted and
>  rendered as an empty line.
> @@ -190,23 +190,25 @@
>  which, if a unit is not provided, will instead interpret the string as
>  literal text.
>  .Ss Sentence Spacing
> -When composing a manual, make sure that your sentences end at the end of
> +When composing a manual, make sure that sentences end at the end of
>  a line.
>  By doing so, front-ends will be able to apply the proper amount of
>  spacing after the end of sentence (unescaped) period, exclamation mark,
>  or question mark followed by zero or more non-sentence closing
> -delimiters (
> -.Ns Sq \&) ,
> +delimiters
> +.Po
> +.Sq \&) ,
>  .Sq \&] ,
>  .Sq \&' ,
> -.Sq \&" ) .
> +.Sq \&"
> +.Pc .
>  .Sh MANUAL STRUCTURE
>  Each
>  .Nm
> -document must contain contains at least the
> +document must contain the
>  .Sx \&TH
>  macro describing the document's section and title.
> -It may occur anywhere in the document, although conventionally, it
> +It may occur anywhere in the document, although conventionally it
>  appears as the first macro.
>  .Pp
>  Beyond
> @@ -291,10 +293,7 @@
>  This is useful when implementing standard functions that may have side
>  effects or notable algorithmic implications.
>  .It Em RETURN VALUES
> -This section is the dual of
> -.Em EXIT STATUS ,
> -which is used for commands.
> -It documents the return values of functions in sections 2, 3, and 9.
> +This section documents the return values of functions in sections 2, 3, and 9.
>  .It Em ENVIRONMENT
>  Documents any usages of environment variables, e.g.,
>  .Xr environ 7 .
> @@ -303,10 +302,8 @@
>  It's helpful to document both the file name and a short description of how
>  the file is used (created, modified, etc.).
>  .It Em EXIT STATUS
> -Command exit status for section 1, 6, and 8 manuals.
> -This section is the dual of
> -.Em RETURN VALUES ,
> -which is used for functions.
> +This section documents the command exit status for
> +section 1, 6, and 8 utilities.
>  Historically, this information was described in
>  .Em DIAGNOSTICS ,
>  a practise that is now discouraged.
> @@ -314,7 +311,7 @@
>  Example usages.
>  This often contains snippets of well-formed,
>  well-tested invocations.
> -Make doubly sure that your examples work properly!
> +Make sure that examples work properly!
>  .It Em DIAGNOSTICS
>  Documents error conditions.
>  This is most useful in section 4 manuals.
> @@ -351,13 +348,13 @@
>  Common misuses and misunderstandings should be explained
>  in this section.
>  .It Em BUGS
> -Known bugs, limitations and work-arounds should be described
> +Known bugs, limitations, and work-arounds should be described
>  in this section.
>  .It Em SECURITY CONSIDERATIONS
>  Documents any security precautions that operators should consider.
>  .El
>  .Sh MACRO SYNTAX
> -Macros are one to three three characters in length and begin with a
> +Macros are one to three characters in length and begin with a
>  control character,
>  .Sq \&. ,
>  at the beginning of the line.
> @@ -444,8 +441,8 @@
>  .Nm
>  manuals.
>  .Ss Block Macros
> -Block macros are comprised of a head and body.
> -Like for in-line macros, the head is scoped to the current line and, in
> +Block macros comprise a head and body.
> +As with in-line macros, the head is scoped to the current line and, in
>  one circumstance, the next line (the next-line stipulations as in
>  .Sx Line Macros
>  apply here as well).
> @@ -602,8 +599,8 @@
>  and
>  .Sx \&r .
>  .Ss \&IB
> -Text is rendered alternately in italics and bold face.  Whitespace
> -between arguments is omitted in output.
> +Text is rendered alternately in italics and bold face.
> +Whitespace between arguments is omitted in output.
>  .Pp
>  See
>  .Sx \&BI
> @@ -626,7 +623,7 @@
>  The
>  .Cm width
>  argument defines the width of the left margin and is defined by
> -.Sx Scaling Widths ,
> +.Sx Scaling Widths .
>  It's saved for later paragraph left-margins; if unspecified, the saved or
>  default width is used.
>  .Pp
> @@ -943,7 +940,7 @@
>  The stand-alone implementation that is part of the
>  .Xr mandoc 1
>  utility written by Kristaps Dzonsons appeared in
> -.Ox 4.6.
> +.Ox 4.6 .
>  .Sh AUTHORS
>  This
>  .Nm
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv