Date: Wed, 23 Jun 1999 18:44:37 -0500 (CDT) From: Mike Pritchard <mpp@mpp.pro-ns.net> To: grog@lemis.com (Greg Lehey) Cc: taavi@uninet.ee (Taavi Talvik), asmodai@wxs.nl (Jeroen Ruigrok/Asmodai), mike@smith.net.au (Mike Smith), hm@hcs.de, dfr@nlsystems.com, peter@FreeBSD.ORG, hackers@FreeBSD.ORG (FreeBSD Hackers) Subject: Re: All this and documentation too? (was: cvs commit: src/sys/isa sio.c) Message-ID: <199906232344.SAA00888@mpp.pro-ns.net> In-Reply-To: <19990623154745.D581@freebie.lemis.com> from Greg Lehey at "Jun 23, 1999 03:47:45 pm"
next in thread | previous in thread | raw e-mail | index | archive | help
> On Wednesday, 23 June 1999 at 9:12:12 +0300, Taavi Talvik wrote: > > On Tue, 22 Jun 1999, Jeroen Ruigrok/Asmodai wrote: > > If you write man pages first time, it is quite close to clack magic. > > It would be really nice if someone comfortant with troff/nroff etc. > > would make Handbook page describing how to get started with it. > > Maybe even templates or script generating page sceletion and pointers to > > them under some handbook entry > > > ... > > There's a man page for it :-) > > mdoc.samples(7). Now tell me that that's not intuitive. And in /usr/share/examples/mdoc there are three example templates for section 1, 3, and 4 manual pages. - Sections 1, 6 and 8 are all pretty much the same (user commands, games, administrator commands). - Sections 2 and 3 are pretty much the same (system calls and library functions). - Section 4 is used to describe external kernel interfaces. The individual formats can vary. The most common format is defined in example.4. - Section 5 is used to describe file formats, and due to the individual requirements of each different man page, there really isn't a general purpose template that would cover most cases. What I usually do for this section is to find another man page that I want mine to look like and edit it to suit my taste. - Section 7 is for misc. documentation. Format varys with what is being documented. - Section 9 is similar to section 2, with a sprinkling of section 4 in some cases, and then some more depending on the interface. Again, for something fancy, look for man page that has all of the different sections you want in your own man page and edit to taste. Also refer to mdoc.samples(7) and mdoc(7). mdoc(7) briefly describes all of the different mdoc macros. mdoc.samples(7) describes them all, along with examples of how each one should be used. As someone who has written a number of manual pages for FreeBSD, I think that for most things the examples in /usr/share/examples/mdoc should serve most would be man page writers fine (I use them). For more complex man pages, I usually just grab an existing man page and edit to tase. -Mike -- Mike Pritchard mpp@FreeBSD.ORG or mpp@mpp.pro-ns.net To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-hackers" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199906232344.SAA00888>