From owner-freebsd-doc Mon Nov 13 8: 5:59 2000 Delivered-To: freebsd-doc@freebsd.org Received: from blizzard.sabbo.net (ns.sabbo.net [193.193.218.18]) by hub.freebsd.org (Postfix) with ESMTP id BB0BB37B4CF; Mon, 13 Nov 2000 08:05:52 -0800 (PST) Received: from vic.sabbo.net (root@vic.sabbo.net [193.193.218.109]) by blizzard.sabbo.net (8.10.1/8.10.1) with ESMTP id eADG5k432703; Mon, 13 Nov 2000 18:05:47 +0200 Received: from FreeBSD.org (big_brother.vega.com [192.168.1.1]) by vic.sabbo.net (8.11.1/8.9.3) with ESMTP id eADG5n014680; Mon, 13 Nov 2000 18:05:50 +0200 (EET) (envelope-from sobomax@FreeBSD.org) Message-ID: <3A10115C.B6DC1DD4@FreeBSD.org> Date: Mon, 13 Nov 2000 18:05:49 +0200 From: Maxim Sobolev Organization: Vega International Capital X-Mailer: Mozilla 4.76 [en] (WinNT; U) X-Accept-Language: uk,ru,en MIME-Version: 1.0 To: Sheldon Hearn Cc: Andrzej Bialecki , doc@FreeBSD.org Subject: Re: cvs commit: src/lib/libc/gen sysctl.3 src/release/picobsd/tinyware/sps README sps.c References: <43428.974102765@axl.fw.uunet.co.za> Content-Type: text/plain; charset=koi8-r Content-Transfer-Encoding: 7bit Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org Sheldon Hearn wrote: > On Sat, 11 Nov 2000 08:12:39 PST, Andrzej Bialecki wrote: > > > Modified files: > > lib/libc/gen sysctl.3 > > Log: > > Correct description of KERN_PROC. Add description of KERN_PROC_ARGS. > > > > Revision Changes Path > > 1.40 +14 -3 src/lib/libc/gen/sysctl.3 > > New text should not introduce hard sentence breaks. :-) > > I usually mention this in private, but it seems that these critters are > on the rise again, so I think it's worth bothering everyone again. > > +.El > + > ^^^^ > > This blank line should really be a paragraph marker (Pp). > > +If the third level name is KERN_PROC_ARGS then the command line argument > +array is returned in a flattened form, i.e. zero-terminated arguments > +follow each other. The total size of array is returned. It's also possible > ^^^^^ ^^^^^ > +for a process to set it's own process title this way. > > Hard sentence breaks. Here's the guideline I mail people about line > breaking in manual pages: > > | The line breaking guideline can be explained as follows: > | > | Each sentence should begin on a new line. > | When a sentence is too long to fit on a line comfortably > | (where the subjective interpretation of comfort > | seems to be around 70 characters), > | it should be broken on sentence fragments. > | Breaking sentence fragments on punctuation, > | as done here, > | seems to be popular. > > Lots of people disagree with me about the line length issue, so you > needn't agree with me on that. But the rule about each sentence > beginning on its own line should be adhered to. How about creating `manlint' script, which will search manpage for common inconsistencies (hard breaks, long lines, incorrect macro usage etc)? This would simplify task both for developers and doc team. -Maxim To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message