Date: Thu, 6 Jun 1996 17:17:33 +0200 (MET DST) From: grog@lemis.de (Greg Lehey) To: jfieber@indiana.edu (John Fieber) Cc: doc@FreeBSD.org (FreeBSD Documenters) Subject: Re: Linuxdoc Message-ID: <199606061517.RAA03718@allegro.lemis.de> In-Reply-To: <Pine.NEB.3.93.960606091459.422x-100000@Fieber-John.campusview.indiana.edu> from "John Fieber" at Jun 6, 96 10:04:28 am
next in thread | previous in thread | raw e-mail | index | archive | help
John Fieber writes: > > 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. Sounds like a reasonable thing to examine. You might like to ask Lenny if ORA is prepared to release their conversion tools. FYI, ORA do their formatting with groff, and to do that they convert their SGML base to their .ms variant. For various reasons, I'd rather not be involved in the asking. > 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. I think the things you say later on make this a waste of effort. If you need groff help, though, just ask. > 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. Does it all have to happen at once? I currently have my "how to add a second disk" half finished, and the prospect of finishing it completely with the current DTD scares me. It would be nice to be able to mix the linuxdoc DTD and (for example) DocBook in the sources. That would make transition much easier, too. > 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. Sounds like the thing to do. Greg
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199606061517.RAA03718>