Date: Tue, 26 Feb 2002 16:47:08 -0800 From: Rich Morin <rdm@cfcl.com> To: freebsd-doc@FreeBSD.ORG Subject: Re: FreeBSD manual sets (was: yacc documentation) Message-ID: <p0510030fb8a1d4119a61@[192.168.254.205]> In-Reply-To: <20020226235901.GA23559@panix.com> References: <20020225191122.A15283@chiark.greenend.org.uk> <p051003dfb8a170c0a167@[192.168.254.205]> <20020226182757.GC23959@panix.com> <p05100308b8a1b3e70b91@[192.168.254.205]> <20020226235901.GA23559@panix.com>
next in thread | previous in thread | raw e-mail | index | archive | help
At 6:59 PM -0500 2/26/02, Adam Turoff wrote:
>> ... the papers should be OK for anyone to include.
>
>You mean like in /usr/share/doc/{smm|usd|psd}? :-)
Yep.
>Ya know, I think the days of the Big (Grey|Orange|Beige) Wall are
>thankfully a thing of the past. The manuals have grown to the point
>where what's really needed is a fully integrated, cross referenced
>and hyperlinked online manuals. Much like KDE provides with
>man:troff type urls in Konqueror.
Online docs have significant merits, but so do printed docs. I don't
see a conflict, however; use either or both, depending on your needs!
>But...
>
>> Consequently, DOSSIER provides topical volumes ...
>
>...this approach seems like the happy medium. I don't know what the
>value of a printed version of section 4 would be, or how complete
>section 3 would be if it omits what manpages for what many programmers
>use today: perl, python, java, ruby, etc. 30 years ago, a printed
>version of man(3) was *very* useful because everyone was using C
>or C APIs.
Well, FreeBSD's section 9 takes up a lot of "Kernel: FreeBSD". I add in
some other pages having to do with tools for working on the kernel, etc.
Sections 2, 4, and 5 would each fill a DOSSIER volume quite nicely. The
other sections, however, are a bit more problematic.
<RANT>
One of the peculiarities of the current manual organization is that name
spaces are spread across sections. Sections 2 & 3 both contain C calls;
does anyone really care about the distinction between library functions
and system calls? Sections 1 & 8 both contain commands, but RedHat
differs with FreeBSD on the placement of some commands. As a result, a
user can't predict which section a given page is in! Adding Perl calls
into section 3 does NOT help the confusion. Grumble...
</RANT>
>What would be truly nice if {smm|usd|psd|*} were to be resurrected
>to be current and modern. Many of the documents in /usr/src/doc/en
>would be applicable, but there are many gaps to be filled. Of course,
>with an all-vounteer project, this would be more than a simple matter
>of content aggregation to fill in the missing pieces...
There is actually quite a bit of content lying around. Start with the
BSD papers, add in materials from assorted conferences and journals, and
you end up with a quite respectable bibliography. DOSSIER has shown that
it can handle the mechanics of formatting and printing, but someone still
has to pick the papers and obtain the appropriate permissions.
I'm actively looking for "area experts" who would like to pick papers for
topical volumes. If you want to see a volume happen and can spare a few
hours to put together a TOC, please get in touch! Obtaining permissions
can be anything from trivial to impossible, but I'm always willing to ask.
-r
--
email: rdm@cfcl.com; phone: +1 650-873-7841
http://www.cfcl.com/rdm - my home page, resume, etc.
http://www.cfcl.com/Meta - The FreeBSD Browser, Meta Project, etc.
http://www.ptf.com/dossier - Prime Time Freeware's DOSSIER series
http://www.ptf.com/tdc - Prime Time Freeware's Darwin Collection
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?p0510030fb8a1d4119a61>