Date: Thu, 6 Jun 1996 10:04:28 -0500 (EST) From: John Fieber <jfieber@indiana.edu> To: Greg Lehey <grog@lemis.de> Cc: "Jordan K. Hubbard" <jkh@time.cdrom.com>, FreeBSD Documenters <doc@FreeBSD.org> Subject: Re: Linuxdoc Message-ID: <Pine.NEB.3.93.960606091459.422x-100000@Fieber-John.campusview.indiana.edu> In-Reply-To: <199606061232.OAA02995@allegro.lemis.de>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 6 Jun 1996, Greg Lehey wrote: > There's been so much mail on this subject in the last couple of days > that I haven't found time to analyse it, but I think we can say: > > - Nobody likes TeX or groff that much. > - SGML would be a good idea > - Linuxdoc is probably a bad choice > - We need a documented DTD. > > What do you say we examine DocBook? A benefit of Docbook is that it is becoming a defacto standard exchange dtd for computer system documentation, software in particular. It is very rich, but also pretty complex. Fortunately it is documented. Unfortunately, due to its complexity it is quite a chore to convert to (troff|tex|html). The current tool that does our conversion grunt work (sgmlsasp) is totally inadequate. Since we are in general agreement that we are probably on the right train, but the color of the upholstry is making us sick, I'm looking at the following: 1) Replace sgmlsasp with instant (anyone got a better name?). It Intstant was developed by OSF to facilitate conversions of SGML documents. Its small (text: 65536, data: 4096, bss 896), pretty fast, has a BSD compatible license, and is *much* more powerful than sgmlsasp. It parses the whole document into a tree, and then traverses the tree applying rules that you specify in a "transpec" file. Rules can reference other rules and most importantly, rules can search the tree for other nodes (i.e. cross reference targets). There are sophisticated mechanisms for specifying rule matching criteria (which rules get applied to which nodes) that include presence of and/or values of attributes in the node, or in ancestor, parent, sibling, or child nodes. You can create variables to stash things, and when instant can't do something itself, rules can call execute system commands. On the down side, the tool clearly has some rough edges. In particular the transpec file format is difficult to use. I'm working on a little hack to allow the transpec files to be written in sgml which will make writing them much less painful. I have instant bmake'd and it could drop in more or less instantly, although it can't be used until the next two steps are done. 2a) Using intstant makes de-crufting the linuxdoc DTD highly desirable. In particular, there is a lot of stuff in the DTD that is there to overcome problems in the conversion. I speak mainly of all the SHORTREF stuff that has caused me no end of frustration, but there are other cleaning opportunities as well. This decrufting is in progress. 2b) To move over from sgmlsasp to instant, "transpec" files need to be created. Since instant provides all the functionality of sgmlsasp, hacked up a perl script to convert sgmlsasp mapping files to instant transpec files. With these, instant becomes a plug-in replacement for sgmlasp which could then be removed from FreeBSD. I am currently testing the newly generated transpec files. 3) The recent issue of tables has inspired me to look more closely at the tables in linuxdoc. What I propose is to remove the tables from linuxdoc before we have documents that use them and replace them with CALS tables from Docbook. CALS tables are used in quite a few DTDs. I think this will be relatively painless to do at the DTD level and I already have some primitive cals table -> html conversion stuff for instant. I could probably hack the cals -> LaTeX, but would definately need help with cals -> groff. 4) Up to this point, we are using a cleaned up linuxdoc DTD, but with a new improved conversion engine. The improved conversion engine will make enhancements to the DTD much easier to implement. This is fairly important because the Handbook is over 350 pages and the prospect of converting it to another DTD is not something i'm looking forward to doing. I think it ultimately will happen, but not this week. For those concerned about the L-word, the DTD will be changed enough that would could call it something else. :) 5) If we bring in docbook tables, we may as well bring in Docbook. It wouldn't be immediately used, but it would be at least surveying the land and ultimately paving the way. Docbook is around 130k and the ISO entity sets are another 90k. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.NEB.3.93.960606091459.422x-100000>