Date: Tue, 16 Jan 2001 17:27:51 +0000 From: Nik Clayton <nik@freebsd.org> To: Martin Horcicka <horcicka@vol.cz> Cc: freebsd-doc@freebsd.org Subject: Re: man, TOC, xml... Message-ID: <20010116172751.A3414@canyon.nothing-going-on.org> In-Reply-To: <Pine.BSF.4.30.0101161434550.25916-100000@k2.vol.cz>; from horcicka@vol.cz on Tue, Jan 16, 2001 at 03:51:34PM %2B0100 References: <Pine.BSF.4.30.0101161434550.25916-100000@k2.vol.cz>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, Jan 16, 2001 at 03:51:34PM +0100, Martin Horcicka wrote:
> 1. classification
> -----------------
> In my opinion this is the main problem of man. Pages are classified to
> nine sections but these are too few to find the right page quickly when
> one is searching by subject. I am not sure if more sections would help
> - maybe it would be better to develop some mechanism to automatically
> create table of contents or something like this.
Man pages aren't really designed for that sort of information. If
you're looking for a broad overview of a topic then the other
documentation is going to be better. Man pages excel at providing
concise information about a particular command, library call, or
interface.
> 2. internal structure
> ---------------------
> groff is really not my favourite typesetting system and -mdoc macro
> package tries to do with it something which is usually used sgml or xml
> for. In addition, use of groff brings the unability to check the
> correctness of the man page internal structure (in contrast to xml), not
> mentioning easy internationalization etc. Would not it be better to
> develop a DTD for xml and some format transformation system to create new
> manual system in xml? It should not be a problem to make the old and the
> new system coexist together.
DocBook already completely supports everything necessary to mark up
manual pages. Which begs the question "Why don't we support man pages
marked up in DocBook?"
1. The existing mechanism for converting DocBook to other formats
(in particular, HTML, text, and Postscript) is resource intensive.
2. Other, strictly standards following approaches (using the XML DTD,
putting a Java parser and library in the base system) are also
resource intensive.
3. I haven't played around with things like refentry2man yet
http://refentry2man.pld.org.pl/, which might solve the problem.
Note that refentry2man has the basic problem of being GPL'd, which
precludes its use in the FreeBSD base system (or, at the very
least, will lead to a flamewar of immense proportions -- I have no
intention of trying to fight that battle).
We would not be the first Unix to adopt DocBook for man pages. Solaris
does -- Solaris 7 had a mix of DocBook and traditional *roff manual
pages, and, AIUI, Solaris 8 is all DocBook (or rather, SolBook, Sun's
custom, cut down version of DocBook).
I would support an effort to get DocBook in to the base system, but I
don't have the time right now to drive such an effort. I will, however,
cheerfully sit on the sidelines shouting encouragement and offering
advice.
N
--
Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95.
Telephone line, $24.95 a month. Software, free. USENET transmission,
hundreds if not thousands of dollars. Thinking before posting, priceless.
Somethings in life you can't buy. For everything else, there's MasterCard.
-- Graham Reed, in the Scary Devil Monastery
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?20010116172751.A3414>