Existing Doc Systems, Part 2 (SGML)


Kim Lester (kim@dfusion.com.au)
Wed, 12 Jan 2000 18:12:14 +0000


         Existing Doc Systems, Part 2 (SGML)
         ===================================

 Overview of SGML
 ----------------
   SGML: Standard Generalised Markup Language
   SGML is a language definition language (SIO 8879:1986).
   It is quite big and sophisticated/complex (concept is simple)

   Many diverse groups are moving to SGML (and XML) due to it's
   flexibility in assigning meaning to document text using "tags"
   (keywords embedded in the text data)
   It is like a free-form database for text based information.
   It makes the "database" conform to the text rather than the other
   way around.
  
   The ODF should probably take the form of an XML DTD.
   
   
   SGML Intro
        http://www.techapps.co.uk/iihb_sgml.html
   
   More technical Intro
        http://www.personal.u-net.com/~sgml/sgml.htm
 
 
   Electronic Text Interchange group (using SGML/DTD):
          http://www-tei.uic.edu/orgs/tei/intros/teiu5.html
          (It has a good outline of the concepts)
   
   Another link:
         http://www.oasis-open.org/cover
         
         
   The following projects are an example of the breadth of SGML's
   scope (taken from http://www.uslynx.com/sgml101.htm)
   
       CALS : 28000 (IGES);
              28001a (SGML and DTDs);
              28002 (Group 4 raster); 28003 (CGM);
              1840a tape standard
       JCALS -- military weopans documentation
       AAP -- publishing
       SNE/Cercle
       ATA -- aircraft documentation
       TCIF -- telecommunications equipment documentation
       AECMA
       SEC's EDGAR
       TEI (Text Encoding Initiative) -- scholarly publishing
       OSF (Novell, Silicon Graphics)
       SAE J2008 (Society of Automotive Engineers) -- automobile docs
       CAD Framework Initiative
       ICADD - exchange of textbook information
              (will produce Braille Search & Retrieval engine)
 
 
 DTDs (Document Type Definitions)
 ----
 
         SGML is a language for defining document content.
         A DTD is a specific sets of tag definitions.
        DTD customises SGML/XML by providing a specific set of
        tags/rules for a specific purpose (eg indexing, author,
        subject, date, id, etc).
        
        DTD may cover any topic not just publishing, eg there
        is a chemical database DTD. DTDs are general as any
        potential database requirement.
        
        A couple of technical documentation specific DTDs:
 
         Linuxdoc - I believe this has been deprecated in favour
                         of the more sophisticated and more general
                         DocBook ???? ( See LDP)
         
         DocBook - Developed by OASIS (and SGML group for open doc
                         and data exchange)
                   Designed for computer/software documentation
                   DocBook is apparently used by many large companies
                   OASIS is generally moving from SGML to XML.
                   
                   DocBook Intro:
                                   http://www.oasis-open.org/docbook/
                                   
                   Some DocBook Tools:
                                   http://sourceware.cygnus.com/docbook-tools/
                                   (also SGMLtools noted elsewhere)
              
 
 DSSSLs
 ------
   Document Style Semantics and Specification Language
         
   DSSSLs are Output Definition things. They define how the
   tags appear on the chosen output media.
   
   Some links:
           http://www.mulberrytech.com/dsssl/dsssldoc/cookbook/
        http://www.mulberrytech.com/dsssl/dsssldoc/handbook.html

   Jade is an free DSSSL processor (included with SGMLtools)
           http://www.jclark.com/jade/
         
         
 SGML Editors
 ------------
 
    I am not aware of any (free) GUI SGML savvy editors.
    There is an editor supporting SGMLtools (klyx or LyX ?)
    Apparently EMACS has a smart SGML mode package (PSGML)
            (Emacs has everything, but do you have enough fingers
             to invoke the commands: Esc-Meta-Alt-Ctrl-Shift-Tab... :-) )

 SGML Tools
 ----------
 
   Any standard is useless without tools. SGML having evolved out
   of academic theoretical discussions initially had no tools
   to support it. That has changed but there appear to be
   few free tools (from a rough web search). I think that part
   of the reason for this is the potential complexity of SGML
   grammers (hence XML's development).

   One tool site:
           http://www.infotek.no/sgmltool/guide.htm

   One set of free tools is the SGMLtools project. Its stated
   intention is to produce tools for technical software documentation
   
   http://www.us.sgmltools.org/
     
   This toolset understands a subset (how much ??) of SGML.
   I _think_ Version 2.x can output in the following formats:
    
        TeX,
        HTML
        XML flow object tree [whatever that is...]
        Framemaker MIF
        RTF
        DVI (?) [can get there via TeX anyway]
        Postscript (?) [can get there via TeX anyway]
        plain text (?)
        PDF (?)
        
        also script to help convert from LinuxDoc to DocBook
        
   Version 1.0 (linuxDoc source format only) can output to at least
   the following. I'm not sure how version 2.0 stands:
   
           LaTeX
           HTML
           RTF
        GNU info,
        LyX,
        plain text (via groff)
        man pages (via groff)

  Notes:
          * The project has been suspended due to lack of time.
              (Anyone want to start it up again?)
           * SGMLtools was originally called Linuxdoc-SGML (from LDP)
              (It was changed because it isn't linux specific)
          * SGMLtools moved away from the Linuxdoc-DTD and
              now embraces the DocBook-DTD "technical doc standard"
                      SGMLtools version 1.x is LinxDoc-DTD
                      SGMLtools version 2.x is DocBook-DTD (ALPHA release)
           
           * I believe that LDP is moving to DocBook-DTD standard too ??
           
        It occurs to me that SGML isn't currently a viewable source
        format either (files would probably have to be converted
        to HTML on the fly etc). In this regard it is no better than
        texInfo. So I shouldn't put tekInfo down on that point.
        (XML may improve matters !?)

Example SGML dource using DocBook DTD
-------------------------------------
        Taken from a DocBook Intro. refer to
       http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html
       (you can see sgml and compare it with the HTML,PS,RTF outputs)
       
========================================
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
  <!ENTITY dilbert-recycle SYSTEM "dilbert-recycle.eps" ndata eps>
  <!ENTITY ui "&mu;ITRON">
  <!ENTITY www "World Wide Web">
  <!ENTITY cygnus "Cygnus">
  <!ENTITY cygnus-full "Cygnus Solutions">
  <!-- <!ENTITY cygnus-full "The company formerly known as Cygnus"> -->
  <!ENTITY cygnus-street-address "
<corpname>Cygnus Solutions</corpname>
<address>
<street>1325 Chesapeake Terrace</street>
<city>Sunnyvale</city>
<state>CA</state>
<postcode> 94089</postcode>
</address>
">
<book id="docbook-intro">
  <!-- I am putting the title in the bookinfo, rather than here as a
  standalone -->
  <bookinfo>
    <date>1998-10-19</date>
    <title>Get Going With DocBook</title>
    <abbrev>DocBook</abbrev>
    <subtitle>Notes for Hackers</subtitle>
    <releaseinfo>documentation in progress</releaseinfo>
    <authorgroup>
      <author>
        <firstname>Mark</firstname>
        <!-- <othername>&ldquo;dude&rdquo;</othername> -->
        <surname>Galassi</surname>
        <affiliation>
          <orgname>&cygnus-full;</orgname>
        </affiliation>
        <!-- <authorblurb>
          <title>Mark Galassi</title>
          <para>
            His home page is at <ulink
            URL="http://nis-www.lanl.gov/~rosalia/">this
            location</ulink>
            </para>
        </authorblurb>
        -->
      </author>
    </authorgroup>
    <address>
      <email>rosalia@cygnus.com</email>
    </address>
    <copyright>
      <year>1998</year>
      <holder>Mark Galassi</holder>
    </copyright>
    <legalnotice><para>
      This document can be freely redistributed according to the terms
      of the GNU General Public License.</para>
    </legalnotice>
    <revhistory>
      <revision>
        <revnumber>0.0</revnumber>
        <date>1997-10-11</date>
        <authorinitials>rosalia@cygnus.com</authorinitials>
        <revremark>Initial revision; mostly just an
          outline</revremark>
      </revision>

....
----------------------------------------------

        Pros
        ----
        Powerful standard
        Flexible
        High quality technical document format already defined
                and in use (DocBook DTD)
        Ability to define sophisticated indexing/structure tags
        Range of output formats supported
        
        Cons
        ----
        Potentially too verbose to hand code large documents.
        Not many editing tools currently available
        (Giving way to XML for web related content)



This archive was generated by hypermail 2.0b3 on Wed Jan 12 2000 - 13:14:53 EST