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 "μ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>“dude”</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