From owner-freebsd-doc Tue Jan 16 8:33:53 2001 Delivered-To: freebsd-doc@freebsd.org Received: from sol.cc.u-szeged.hu (sol.cc.u-szeged.hu [160.114.8.24]) by hub.freebsd.org (Postfix) with ESMTP id 8198437B400 for ; Tue, 16 Jan 2001 08:33:33 -0800 (PST) Received: from petra.hos.u-szeged.hu by sol.cc.u-szeged.hu (8.9.3+Sun/SMI-SVR4) id RAA27365; Tue, 16 Jan 2001 17:33:30 +0100 (MET) Received: from sziszi by petra.hos.u-szeged.hu with local (Exim 3.12 #1 (Debian)) id 14IZ34-0005EC-00 for ; Tue, 16 Jan 2001 17:33:30 +0100 Date: Tue, 16 Jan 2001 17:33:30 +0100 From: Szilveszter Adam To: freebsd-doc@freebsd.org Subject: Re: man, TOC, xml... Message-ID: <20010116173330.B15289@petra.hos.u-szeged.hu> Mail-Followup-To: Szilveszter Adam , freebsd-doc@freebsd.org References: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: ; from horcicka@vol.cz on Tue, Jan 16, 2001 at 03:51:34PM +0100 Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org Hi everybody, I'll take a stab at answering these questions, although I am by no means a man/groff or xml expert, so feel free to ask what I'd been smoking:-) 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. Well if you mean searching, than apropos(1) and (provided it is properly maintained) whatis(1) can be used rather well. These already use a database containing the man pages and their text. Also, in the beginning of each section, there is an intro page that tells you what to expect in that section. This could easily include a (even generated) listing of all pages in that section. (this is currently not the case on FreeBSD) But then again, some sections have so many man pages that it would be dificult to fit them on the screen in a nice manner. > 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. I think that the tradition of using groff to typeset the pages has remained for two reasons: 1) Groff is actually a quite useful and resource-rich typesetting solution, and I for one find it easier to define macros in it than in, say, TeX. The only problem with it is that it lacks localization support to the extent LaTeX eg has it. But this is not a problem for man pages. 2) Groff is usually installed on every system and therefore it is possible to author man pages on almost any system, even if other, partly resource-hungry environments are not installed. This in turn has two consequences: - It is possible (even encouraged) to write local man pages for programs that your users might want to use, or any other topic of interest. (For such use, and abuse check out the alt.sysadmin.recovery man page collection in ports:-) My friends still look at me with big eyes if I tell them to just see knife(8):-)) - It is not necessary to generate all pages beforehand, but rather you just copy the new page onto the system and it will be reformatted upon first access. This formatting takes comparatively little time even on a slow system, which is not always true for say an XML parser. Also, man pages are very often (I'd argue almost exclusively) used on a terminal, for which groff output is better suited because it produces high-quality ASCII text. But if you want, you can also easily format those same pages with no additional software for printing too. Implementing say an XML parser on every system that wants to use man is quite costly and may be slow, and may have undesired dependecies (eg X.) Not implementing it would mean that you first have to reformat each page separately which would make the whole system more rigid. > 3. manual browser > ----------------- > I am sure, some hypertext browser would be really better than the > presently used more/less. In conjunction with the xml manual system it > would be maybe easier to write it. In fact, several browsers already exist for man pages, that even feature a TOC (they show all man pages in an index). You can find such solutions say with Gnome's or KDE's help browser, but even xman (or whatever it is called) from the Xcontrib package is available as a quite low-end solution. You can find others say tkman. Also, in general these ideas (perhaps with the exception of XML which was not available then) essentially mean reinventing the 'info' package from the GNU project (which they indeed prefer over man pages in their programs) Nevertheless, the info package (although it is installed on FreeBSD, you can try it by just typing 'info' and see a TOC which has links to the various sections that you can navigate) did not chatch on outside of GNU and Linux in general because a) writing texinfo docs is not everybody's favorite, linking them up appropriately is even less so upon installation b) the UI (the info program itself) IMHO seriously sucks. But many people find it hard to use, too. By the time you learn how to use the many key combos you may have read all man pages three times... but this is my personal opinion. And this does not mean that the info package was not a good idea. With the advent of X-based browsers the UI problem partly went away, but X never should be made a requirement for using the doxx... > These are my ideas. Could you tell me yours? Sure. Here it is...:-) -- Regards: Szilveszter ADAM Szeged University Szeged Hungary To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message