From owner-freebsd-doc  Thu Dec 14 20:05:49 1995
Return-Path: owner-doc
Received: (from root@localhost)
          by freefall.freebsd.org (8.7.3/8.7.3) id UAA19706
          for doc-outgoing; Thu, 14 Dec 1995 20:05:49 -0800 (PST)
Received: from fieber-john.campusview.indiana.edu (Fieber-John.campusview.indiana.edu [149.159.1.34])
          by freefall.freebsd.org (8.7.3/8.7.3) with SMTP id UAA19700
          for <doc@freebsd.org>; Thu, 14 Dec 1995 20:05:45 -0800 (PST)
Received: (from jfieber@localhost) by fieber-john.campusview.indiana.edu (8.6.12/8.6.12) id XAA06265; Thu, 14 Dec 1995 23:05:41 -0500
Date: Thu, 14 Dec 1995 23:05:40 -0500 (EST)
From: John Fieber <jfieber@indiana.edu>
X-Sender: jfieber@fieber-john.campusview.indiana.edu
To: Richard Coleman <coleman@math.gatech.edu>
cc: doc@freebsd.org
Subject: Re: SGML tools for documentation
In-Reply-To: <199512142352.SAA08801@redwood.skiles.gatech.edu>
Message-ID: <Pine.BSF.3.91.951214224300.29686J-100000@fieber-john.campusview.indiana.edu>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Sender: owner-doc@freebsd.org
Precedence: bulk

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 ============