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

2018-05-15 Thread Rodney W. Grimes 
> On Sun, May 13, 2018 at 8:14 PM, Rodney W. Grimes <
> free...@pdx.rh.cn85.dnsmgr.net> wrote:
> >
> > It did take me some time to track down this "crazy concept you all
> > think I just invented", but it is infact in the GNU groff info
> > documentaton (found on my 5.4 systems in /usr/share/info/groff.info.gz):
> 
> Just to be clear, I don't think these rules apply to FreeBSD. We use
> mandoc. See mandoc(1) for the rules that apply to us.

That is a rather fine line.  mandoc is a replacement set for groff -man,
which is a replacement for troff/nroff man.  What I found are helpful
guidelines for anyone writting groff type input, they still apply to
mandoc.

> 
> And, again, just to be clear, I am also pretty sure the following rule
> doesn't apply:
> 
> >* In keeping with this, it is helpful to begin a new line after every
   ^^
Again, these are helpful things that have been around for a very decades,
and for someone who has worked on a good deal of *roff input, it is truely
helpful in many ways to do this.

As one sample of helpful it makes it usually easier to find things in the
*roff sources when trying to edit a manpage,  Another is it minimizes
diffs when making changes.


> >  comma or phrase, since common corrections are to add or delete
> >  sentences or phrases.
> 
> OTOH, I believe we do have a rule about beginning each sentence on a new
> line. (Again, see mandoc(1).)

Yes

> 
> And, it is easy to figure out whether your page complies with the style
> using mandoc's checkers.

Comply with and being of good style and design are not one and the same.

> For example:
> 
> $ mandoc -W all,stop /usr/share/man/man9/tcp_functions.9.gz
> mandoc: /usr/share/man/man9/tcp_functions.9.gz:284:16: WARNING: new
> sentence, new line
> 
> Jonathan
> 
> PS: I'm happy to be corrected by one of the man page experts, which I most
> certainly am not.

I would encoruage the man page expects to adopt this set of helpful guidelines,
not necessarily making them hard rules,
but at least suggesting one knows about them.


-- 
Rod Grimes rgri...@freebsd.org
___
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: r333494 - head/share/man/man7

2018-05-15 Thread Jonathan Looney 
On Sun, May 13, 2018 at 8:14 PM, Rodney W. Grimes <
free...@pdx.rh.cn85.dnsmgr.net> wrote:
>
> It did take me some time to track down this "crazy concept you all
> think I just invented", but it is infact in the GNU groff info
> documentaton (found on my 5.4 systems in /usr/share/info/groff.info.gz):

Just to be clear, I don't think these rules apply to FreeBSD. We use
mandoc. See mandoc(1) for the rules that apply to us.

And, again, just to be clear, I am also pretty sure the following rule
doesn't apply:

>* In keeping with this, it is helpful to begin a new line after every
>  comma or phrase, since common corrections are to add or delete
>  sentences or phrases.

OTOH, I believe we do have a rule about beginning each sentence on a new
line. (Again, see mandoc(1).)

And, it is easy to figure out whether your page complies with the style
using mandoc's checkers.

For example:

$ mandoc -W all,stop /usr/share/man/man9/tcp_functions.9.gz
mandoc: /usr/share/man/man9/tcp_functions.9.gz:284:16: WARNING: new
sentence, new line

Jonathan

PS: I'm happy to be corrected by one of the man page experts, which I most
certainly am not.
___
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: r333494 - head/share/man/man7

2018-05-13 Thread Rodney W. Grimes 
> On Sat, May 12, 2018, 12:59 AM Rodney W. Grimes <
> free...@pdx.rh.cn85.dnsmgr.net> wrote:
> 
> > > On Fri, May 11, 2018 at 8:26 AM, Rodney W. Grimes
> > >  wrote:
> > > >> @@ -67,7 +72,8 @@ Changes are first committed to CURRENT and then
> > usuall
> > > >>  to STABLE.
> > > >>  Every few years the CURRENT branch is renamed to STABLE, and a new
> > > >>  CURRENT is branched, with an incremented major version number.
> > > >> -Releases are then branched off STABLE and numbered with consecutive
> > minor numbers.
> > > >> +Releases are then branched off STABLE and numbered with consecutive
> > minor
> > > >> +numbers.
> > > >
> > > > Proper place to line break long lines is at conjuncatives such
> > > > as the "and" above, yeilding:
> > >
> > > What?  Are you just inventing these rules out of blue sky?  What
> > > possible reason is there to do as you have proposed?
> >
> > Well known and established man page style rules, documented someplace,
> > which I can not seem to locate right now.
> >
> 
> Could you please find that if possible and share with us?
> Personally I'm about to rewrite some man page and that would be useful in
> my case!

It did take me some time to track down this "crazy concept you all
think I just invented", but it is infact in the GNU groff info
documentaton (found on my 5.4 systems in /usr/share/info/groff.info.gz):


   Here are a few hints for preparing text for input to `gtroff'.

   * First, keep the input lines short.  Short input lines are easier to
 edit, and `gtroff' packs words onto longer lines anyhow.

   * In keeping with this, it is helpful to begin a new line after every
 comma or phrase, since common corrections are to add or delete
 sentences or phrases.

   * End each sentence with two spaces - or better, start each sentence
 on a new line.  `gtroff' recognizes characters that usually end a
 sentence, and inserts sentence space accordingly.

   * Do not hyphenate words at the end of lines - `gtroff' is smart
 enough to hyphenate words as needed, but is not smart enough to
 take hyphens out and join a word back together.  Also, words such
 as "mother-in-law" should not be broken over a line, since then a
 space can occur where not wanted, such as "mother- in-law".


Regards,
-- 
Rod Grimes rgri...@freebsd.org
___
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: r333494 - head/share/man/man7

2018-05-11 Thread Warner Losh 
On Fri, May 11, 2018 at 10:59 AM, Rodney W. Grimes <
free...@pdx.rh.cn85.dnsmgr.net> wrote:

> > On Fri, May 11, 2018 at 8:26 AM, Rodney W. Grimes
> >  wrote:
> > >> @@ -67,7 +72,8 @@ Changes are first committed to CURRENT and then
> usuall
> > >>  to STABLE.
> > >>  Every few years the CURRENT branch is renamed to STABLE, and a new
> > >>  CURRENT is branched, with an incremented major version number.
> > >> -Releases are then branched off STABLE and numbered with consecutive
> minor numbers.
> > >> +Releases are then branched off STABLE and numbered with consecutive
> minor
> > >> +numbers.
> > >
> > > Proper place to line break long lines is at conjuncatives such
> > > as the "and" above, yeilding:
> >
> > What?  Are you just inventing these rules out of blue sky?  What
> > possible reason is there to do as you have proposed?
>
> Well known and established man page style rules, documented someplace,
> which I can not seem to locate right now.
>

No such rule exists, and even if it did, it's never been enforced in the
last 23 years I've been committing to man pages.  I know I'd flat out
ignore you if you told me to do that after a commit I did.

Warner
___
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: r333494 - head/share/man/man7

2018-05-11 Thread Ian Lepore 
On Fri, 2018-05-11 at 08:26 -0700, Rodney W. Grimes wrote:
> [ Charset UTF-8 unsupported, converting... ]
> > 
> > Author: trasz
> > Date: Fri May 11 15:11:53 2018
> > New Revision: 333494
> > URL: https://svnweb.freebsd.org/changeset/base/333494
> > 
> > Log:
> >   Improve development(7):
> >   
> >    - Use Fx when referring to FreeBSD.
> >    - Use Ql instead of Cm for command invocations.
> >    - Remove some redundant Pp macros.
> >    - Use a literal indented Bd instead of a series of Dl macros.
> >   
> >   Submitted by: 0mp@
> >   Reviewed by:  eadler@
> >   MFC after:2 weeks
> >   Differential Revision:https://reviews.freebsd.org/D15126
> > 
> > Modified:
> >   head/share/man/man7/development.7
> > 
> > Modified: head/share/man/man7/development.7
> > ===
> > ===
> > [...]
> >  to STABLE.
> >  Every few years the CURRENT branch is renamed to STABLE, and a new
> >  CURRENT is branched, with an incremented major version number.
> > -Releases are then branched off STABLE and numbered with
> > consecutive minor numbers.
> > +Releases are then branched off STABLE and numbered with
> > consecutive minor
> > +numbers.
> Proper place to line break long lines is at conjuncatives such
> as the "and" above, yeilding:
> Releases are then branched off STABLE
> and numbered with consecutive minor numbers.
> 

The last thing we need is more stupid arbitrary rules that discourage
people from writing manpages. This commit deserves praise, not
pointless nitpicking.

-- 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: r333494 - head/share/man/man7

2018-05-11 Thread Marcelo Araujo 
On Sat, May 12, 2018, 12:59 AM Rodney W. Grimes <
free...@pdx.rh.cn85.dnsmgr.net> wrote:

> > On Fri, May 11, 2018 at 8:26 AM, Rodney W. Grimes
> >  wrote:
> > >> @@ -67,7 +72,8 @@ Changes are first committed to CURRENT and then
> usuall
> > >>  to STABLE.
> > >>  Every few years the CURRENT branch is renamed to STABLE, and a new
> > >>  CURRENT is branched, with an incremented major version number.
> > >> -Releases are then branched off STABLE and numbered with consecutive
> minor numbers.
> > >> +Releases are then branched off STABLE and numbered with consecutive
> minor
> > >> +numbers.
> > >
> > > Proper place to line break long lines is at conjuncatives such
> > > as the "and" above, yeilding:
> >
> > What?  Are you just inventing these rules out of blue sky?  What
> > possible reason is there to do as you have proposed?
>
> Well known and established man page style rules, documented someplace,
> which I can not seem to locate right now.
>

Could you please find that if possible and share with us?
Personally I'm about to rewrite some man page and that would be useful in
my case!

>
> > Conrad
>
> --
> Rod Grimes
> rgri...@freebsd.org
>
>
___
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: r333494 - head/share/man/man7

2018-05-11 Thread Rodney W. Grimes 
> On Fri, May 11, 2018 at 8:26 AM, Rodney W. Grimes
>  wrote:
> >> @@ -67,7 +72,8 @@ Changes are first committed to CURRENT and then usuall
> >>  to STABLE.
> >>  Every few years the CURRENT branch is renamed to STABLE, and a new
> >>  CURRENT is branched, with an incremented major version number.
> >> -Releases are then branched off STABLE and numbered with consecutive minor 
> >> numbers.
> >> +Releases are then branched off STABLE and numbered with consecutive minor
> >> +numbers.
> >
> > Proper place to line break long lines is at conjuncatives such
> > as the "and" above, yeilding:
> 
> What?  Are you just inventing these rules out of blue sky?  What
> possible reason is there to do as you have proposed?

Well known and established man page style rules, documented someplace,
which I can not seem to locate right now.

> Conrad

-- 
Rod Grimes rgri...@freebsd.org
___
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: r333494 - head/share/man/man7

2018-05-11 Thread Conrad Meyer 
On Fri, May 11, 2018 at 8:26 AM, Rodney W. Grimes
 wrote:
>> @@ -67,7 +72,8 @@ Changes are first committed to CURRENT and then usuall
>>  to STABLE.
>>  Every few years the CURRENT branch is renamed to STABLE, and a new
>>  CURRENT is branched, with an incremented major version number.
>> -Releases are then branched off STABLE and numbered with consecutive minor 
>> numbers.
>> +Releases are then branched off STABLE and numbered with consecutive minor
>> +numbers.
>
> Proper place to line break long lines is at conjuncatives such
> as the "and" above, yeilding:

What?  Are you just inventing these rules out of blue sky?  What
possible reason is there to do as you have proposed?

Conrad
___
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: r333494 - head/share/man/man7

2018-05-11 Thread Rodney W. Grimes 
[ Charset UTF-8 unsupported, converting... ]
> Author: trasz
> Date: Fri May 11 15:11:53 2018
> New Revision: 333494
> URL: https://svnweb.freebsd.org/changeset/base/333494
> 
> Log:
>   Improve development(7):
>   
>- Use Fx when referring to FreeBSD.
>- Use Ql instead of Cm for command invocations.
>- Remove some redundant Pp macros.
>- Use a literal indented Bd instead of a series of Dl macros.
>   
>   Submitted by:   0mp@
>   Reviewed by:eadler@
>   MFC after:  2 weeks
>   Differential Revision:  https://reviews.freebsd.org/D15126
> 
> Modified:
>   head/share/man/man7/development.7
> 
> Modified: head/share/man/man7/development.7
> ==
> --- head/share/man/man7/development.7 Fri May 11 14:52:35 2018
> (r333493)
> +++ head/share/man/man7/development.7 Fri May 11 15:11:53 2018
> (r333494)
> @@ -24,16 +24,20 @@
>  .\"
>  .\" $FreeBSD$
>  .\"
> -.Dd April 10, 2018
> +.Dd May 11, 2018
>  .Dt DEVELOPMENT 7
>  .Os
>  .Sh NAME
>  .Nm development
> -.Nd introduction to FreeBSD development process
> +.Nd introduction to
> +.Fx
> +development process
>  .Sh DESCRIPTION
>  .Fx
>  development is split into three major suprojects: doc, ports, and src.
> -Doc is the documentation, such as the FreeBSD Handbook.
> +Doc is the documentation, such as the
> +.Fx
> +Handbook.
>  To read more, see:
>  .Pp
>  .Lk https://www.FreeBSD.org/doc/en/books/fdp-primer/
> @@ -54,7 +58,8 @@ can be found at:
>  .Pp
>  .Lk https://www.FreeBSD.org/doc/en/articles/committers-guide/
>  .Pp
> -FreeBSD src development takes place in the CURRENT branch in Subversion,
> +.Fx
> +src development takes place in the CURRENT branch in Subversion,
>  located at:
>  .Pp
>  .Lk https://svn.FreeBSD.org/base/head
> @@ -67,7 +72,8 @@ Changes are first committed to CURRENT and then usuall
>  to STABLE.
>  Every few years the CURRENT branch is renamed to STABLE, and a new
>  CURRENT is branched, with an incremented major version number.
> -Releases are then branched off STABLE and numbered with consecutive minor 
> numbers.
> +Releases are then branched off STABLE and numbered with consecutive minor
> +numbers.

Proper place to line break long lines is at conjuncatives such
as the "and" above, yeilding:
Releases are then branched off STABLE
and numbered with consecutive minor numbers.

>  .Pp
>  Layout of the source tree is described in
>  .Xr hier 7 .
> @@ -76,7 +82,7 @@ Build instructions can be found in
>  and
>  .Xr release 7 .
>  Kernel APIs are usually documented, use
> -.Cm apropos -s 9 ''
> +.Ql "apropos -s 9 ''"
>  for a list.
>  Regression test suite is described in
>  .Xr tests 7 .
> @@ -88,26 +94,31 @@ such as freebsd-arch@ and freebsd-hackers@:
>  .Pp
>  .Lk https://lists.FreeBSD.org/
>  .Pp
> -To get your patches integrated into the main FreeBSD repository use 
> Phabricator;
> +To get your patches integrated into the main
> +.Fx
> +repository use Phabricator;
>  it is a code review tool that allows other developers to review the changes,
>  suggest improvements, and, eventually, allows them to pick up the change and
>  commit it:
>  .Pp
>  .Lk https://reviews.FreeBSD.org/
> -.Pp
>  .Sh EXAMPLES
>  Check out the CURRENT branch, build it, and install, overwriting the current
>  system:
> -.Dl svnlite co https://svn.FreeBSD.org/base/head src
> -.Dl cd src
> -.Dl make -j8 buildworld buildkernel installkernel
> -.Dl reboot
> +.Bd -literal -offset indent
> +svnlite co https://svn.FreeBSD.org/base/head src
> +cd src
> +make -j8 buildworld buildkernel installkernel
> +reboot
> +.Ed
>  .Pp
>  After reboot:
> -.Dl cd src
> -.Dl make -j8 installworld
> -.Pp
> +.Bd -literal -offset indent
> +cd src
> +make -j8 installworld
> +.Ed
>  .Sh SEE ALSO
> +.Xr svnlite 1 ,
>  .Xr witness 4 ,
>  .Xr build 7 ,
>  .Xr hier 7 ,
> 
> 

-- 
Rod Grimes rgri...@freebsd.org
___
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: r333494 - head/share/man/man7

2018-05-11 Thread Edward Tomasz Napierala 
Author: trasz
Date: Fri May 11 15:11:53 2018
New Revision: 333494
URL: https://svnweb.freebsd.org/changeset/base/333494

Log:
  Improve development(7):
  
   - Use Fx when referring to FreeBSD.
   - Use Ql instead of Cm for command invocations.
   - Remove some redundant Pp macros.
   - Use a literal indented Bd instead of a series of Dl macros.
  
  Submitted by: 0mp@
  Reviewed by:  eadler@
  MFC after:2 weeks
  Differential Revision:https://reviews.freebsd.org/D15126

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

Modified: head/share/man/man7/development.7
==
--- head/share/man/man7/development.7   Fri May 11 14:52:35 2018
(r333493)
+++ head/share/man/man7/development.7   Fri May 11 15:11:53 2018
(r333494)
@@ -24,16 +24,20 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd April 10, 2018
+.Dd May 11, 2018
 .Dt DEVELOPMENT 7
 .Os
 .Sh NAME
 .Nm development
-.Nd introduction to FreeBSD development process
+.Nd introduction to
+.Fx
+development process
 .Sh DESCRIPTION
 .Fx
 development is split into three major suprojects: doc, ports, and src.
-Doc is the documentation, such as the FreeBSD Handbook.
+Doc is the documentation, such as the
+.Fx
+Handbook.
 To read more, see:
 .Pp
 .Lk https://www.FreeBSD.org/doc/en/books/fdp-primer/
@@ -54,7 +58,8 @@ can be found at:
 .Pp
 .Lk https://www.FreeBSD.org/doc/en/articles/committers-guide/
 .Pp
-FreeBSD src development takes place in the CURRENT branch in Subversion,
+.Fx
+src development takes place in the CURRENT branch in Subversion,
 located at:
 .Pp
 .Lk https://svn.FreeBSD.org/base/head
@@ -67,7 +72,8 @@ Changes are first committed to CURRENT and then usuall
 to STABLE.
 Every few years the CURRENT branch is renamed to STABLE, and a new
 CURRENT is branched, with an incremented major version number.
-Releases are then branched off STABLE and numbered with consecutive minor 
numbers.
+Releases are then branched off STABLE and numbered with consecutive minor
+numbers.
 .Pp
 Layout of the source tree is described in
 .Xr hier 7 .
@@ -76,7 +82,7 @@ Build instructions can be found in
 and
 .Xr release 7 .
 Kernel APIs are usually documented, use
-.Cm apropos -s 9 ''
+.Ql "apropos -s 9 ''"
 for a list.
 Regression test suite is described in
 .Xr tests 7 .
@@ -88,26 +94,31 @@ such as freebsd-arch@ and freebsd-hackers@:
 .Pp
 .Lk https://lists.FreeBSD.org/
 .Pp
-To get your patches integrated into the main FreeBSD repository use 
Phabricator;
+To get your patches integrated into the main
+.Fx
+repository use Phabricator;
 it is a code review tool that allows other developers to review the changes,
 suggest improvements, and, eventually, allows them to pick up the change and
 commit it:
 .Pp
 .Lk https://reviews.FreeBSD.org/
-.Pp
 .Sh EXAMPLES
 Check out the CURRENT branch, build it, and install, overwriting the current
 system:
-.Dl svnlite co https://svn.FreeBSD.org/base/head src
-.Dl cd src
-.Dl make -j8 buildworld buildkernel installkernel
-.Dl reboot
+.Bd -literal -offset indent
+svnlite co https://svn.FreeBSD.org/base/head src
+cd src
+make -j8 buildworld buildkernel installkernel
+reboot
+.Ed
 .Pp
 After reboot:
-.Dl cd src
-.Dl make -j8 installworld
-.Pp
+.Bd -literal -offset indent
+cd src
+make -j8 installworld
+.Ed
 .Sh SEE ALSO
+.Xr svnlite 1 ,
 .Xr witness 4 ,
 .Xr build 7 ,
 .Xr hier 7 ,
___
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"