Date: Thu, 14 Dec 1995 23:05:40 -0500 (EST) From: John Fieber <jfieber@indiana.edu> To: Richard Coleman <coleman@math.gatech.edu> Cc: doc@freebsd.org Subject: Re: SGML tools for documentation Message-ID: <Pine.BSF.3.91.951214224300.29686J-100000@fieber-john.campusview.indiana.edu> In-Reply-To: <199512142352.SAA08801@redwood.skiles.gatech.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 14 Dec 1995, Richard Coleman wrote: > pages, but we would like to swith to something that would allow > us to translate the base documentation into multiple formats. > I understand that the FreeBSD project is now using some SGML > tools for it's documentation. Is that correct?. It that > how the FreeBSD Handbook is being done? If this is true, I > would like to find out more info about what tools you use. > If possible, I would like to acquire copies of these tools. If you have FreeBSD 2.1, you have all the tools. :) An SGML document has three parts: 1 An SGML declaration (/usr/share/sgml/FreeBSD/dtd/linuxdoc.dec) that describes a bunch of esoteric stuff about how an SGML tool should deal with the document. It defines things like what characters are used as tag delimiters (<, >, </), the character set used and a bunch of other things. You pretty much don't have to worry about this. 2 A document type definition (DTD). This sets up the rules for what tags may occur in a document, what attributes they can have and where in a document they can appear. (eg you can't put a <sect1> inside a <sect2>). The tags delimit elements. Elements are just containers that can hold text (#PCDATA) or other elements. The definition of what a particular element can contain is called the content model. The DTD used for the handbook is /usr/share/sgml/FreeBSD/dtd/linuxdoc. 3 A document instance. The SGML declaration is of little concern to you. The DTD is **critical**. Having worked with the linuxdoc DTD for a while, would advise against using it. I'm looking at moving the handbook to either the DocBook DTD, or the OSF book DTD. As far as processing tools, you need an SGML parser which is included with FreeBSD (sgmls). This digests chews up the document and spits out the document in a form that is trivial to parse with a program which will (hopefully) do something intelligent. There is a companion to sgmls, sgmlsasp, which will map sgml tags to whatever you want. This is a very primitive way of dealing with the conversion and has been a great limitation on what I have been able to do with the handbook. I have a tool called instant that came with the OSF DTD that is much more powerful, but has a lot of rough edges. Ultimately a tool that implements DSSSL, a companion standard to SGML, will address most of the issues/problems of rendering SGML documents. In the meantime, unless you fork out some large piles of money for commercial products, we are stuck with less than optimal tools. -john == jfieber@indiana.edu =========================================== == http://fieber-john.campusview.indiana.edu/~jfieber ============
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSF.3.91.951214224300.29686J-100000>