* man.7 tweaks @ 2010-07-24 13:32 Jason McIntyre 2010-07-24 13:59 ` Ingo Schwarze 0 siblings, 1 reply; 5+ messages in thread From: Jason McIntyre @ 2010-07-24 13:32 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: man.7 tweaks 2010-07-24 13:32 man.7 tweaks Jason McIntyre @ 2010-07-24 13:59 ` Ingo Schwarze 2010-07-24 14:51 ` Jason McIntyre 2010-07-24 15:04 ` Jason McIntyre 0 siblings, 2 replies; 5+ messages in thread From: Ingo Schwarze @ 2010-07-24 13:59 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: man.7 tweaks 2010-07-24 13:59 ` Ingo Schwarze @ 2010-07-24 14:51 ` Jason McIntyre 2010-07-24 18:47 ` Ingo Schwarze 2010-07-24 15:04 ` Jason McIntyre 1 sibling, 1 reply; 5+ messages in thread From: Jason McIntyre @ 2010-07-24 14:51 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: man.7 tweaks 2010-07-24 14:51 ` Jason McIntyre @ 2010-07-24 18:47 ` Ingo Schwarze 0 siblings, 0 replies; 5+ messages in thread From: Ingo Schwarze @ 2010-07-24 18:47 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: man.7 tweaks 2010-07-24 13:59 ` Ingo Schwarze 2010-07-24 14:51 ` Jason McIntyre @ 2010-07-24 15:04 ` Jason McIntyre 1 sibling, 0 replies; 5+ messages in thread From: Jason McIntyre @ 2010-07-24 15:04 UTC (permalink / raw) To: discuss 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2010-07-24 18:48 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2010-07-24 13:32 man.7 tweaks Jason McIntyre 2010-07-24 13:59 ` Ingo Schwarze 2010-07-24 14:51 ` Jason McIntyre 2010-07-24 18:47 ` Ingo Schwarze 2010-07-24 15:04 ` Jason McIntyre
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).