Re: [gentoo-user] Re: writing man pages (gentoo conventions)

[Joerg Schilling]

James <wireless@×××××××××××.com> wrote:

> Joerg Schilling <Joerg.Schilling <at> fokus.fraunhofer.de> writes:
>
>
> > 	man -s5 man
>
> man 7 man

If you like to read the original aman -s5 man, look here:

	http://schillix.sourceforge.net/man/man5/man.5.html

It contains a cookbook for a typical man page.

> > BTW: Use other (good) man pages as reference and avoid the BSD doc format
> > that  was introduced while the AT&T lawsuit was active.
>
> Yea, I learned 'monkey see monkey' do a log time ago, to get along;
> got an explicit example or template or guide in mind?

See man(5) above.

Also check the man pages from the schily tools that have been written to be 
highly portable. Eric Raymond contacted me several times when writing his
documentation tools...

If you like to get a name of a man page that contains most possible constructs, 
I recommend to read the revised Bourne Shell man page that was created for the 
portable Bourne Shell:

	http://schillix.sourceforge.net/man/man1/bosh.1.html

In contrast to the typical Solaris man pages that have been bowdlerized by a 

	troff -> sgml -> troff 

conversion using bad tools, my Bourne Shell man page has been manully fixed to 
again follow the man style rules. This corrected Bourne Shell man source also 
verifies that a troff based man page is really readable in source as well. Note 
that a typical man page should be written as floating text and prefer the *roff
macros from man(5) in favor of \f font switches if possible.

See:

	https://sourceforge.net/projects/schilytools/files/

for a schily tools tarball.

Jörg

-- 
 EMail:joerg@××××××.net                    (home) Jörg Schilling D-13353 Berlin
       joerg.schilling@××××××××××××××××.de (work) Blog: http://schily.blogspot.com/
 URL:  http://cdrecord.org/private/ http://sourceforge.net/projects/schilytools/files/'