Date: Wed, 23 Jun 1999 07:47:36 -0700 (PDT) From: David Wolfskill <dhw@whistle.com> To: asmodai@wxs.nl, taavi@uninet.ee Cc: hackers@freebsd.org Subject: Re: All this and documentation too? (was: cvs commit: src/sys/isa sio.c) Message-ID: <199906231447.HAA97605@pau-amma.whistle.com> In-Reply-To: <Pine.BSF.3.95.990623090548.13324B-100000@ns.uninet.ee>
next in thread | previous in thread | raw e-mail | index | archive | help
>Date: Wed, 23 Jun 1999 09:12:12 +0300 (EEST) >From: Taavi Talvik <taavi@uninet.ee> >If you write man pages first time, it is quite close to clack magic. It may seem that way (ref. Arthur C. Clark), but I respectfully disagree. >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 When I have written man pages (for internal scripts & things -- the only thing I've been able to contribute back to the community of late was a small patch to amd (libamu/mount_fs.c), and that didn't warrant any man page changes), I've picked up the source for some other man page that I thought was put together well, copied it, and then started changing the content as appropriate, with the man pages for mdoc(7) and mdoc.samples(7) in auxiliary windows for reference... along with another window for trying out the results. The results have generally been quite usable, and considerably better than nothing. For me, there are typically two big obstacles: * forming a clear idea of what needs to be written and * getting started in the first place. (Well, there's the meta-obstacle of more things to do than time to do them, and changing priorities for many of these things.) One of the big advantages we have is the ability to start with others' work, and improve on it or adapt it to new uses. (The "we" there is somewhat context-sensitive. In the context of the man pages, the referent may be taken as the community of folks who have historically had access to the troff sources for the man pages. I am aware of only a couple of aberrant UNIX-ish systems that only provided the pre-formatted (and sometimes, compressed) man pages; I believe that most folks using UNIX have had access to the "real thing" -- and certainly anyone working with an "Open Source" UNIX(-like) system has access to them.) Cheers, david -- David Wolfskill dhw@whistle.com UNIX System Administrator voice: (650) 577-7158 pager: (888) 347-0197 FAX: (650) 372-5915 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?199906231447.HAA97605>