[Glastonbury] MiniTutorial : SGML/XML editing

[Martin Wheeler]

============================================================================
A Guide to SGML/XML document editing and publication on GNU/Linux systems

version 0.1

Martin S. Wheeler
mwheeler at startext.co.uk

November 2004

[NOTE: this document assumes that the reader has a rudimentary grasp of what
is meant by SGML markup; the types of documents it applies to; and why it is
being used.]

Editing, then publishing documents using SGML/XML is a three-stage process.

The first stage: "text creation" is itself a two-part activity.
First, the basic text has to be created and written down.
This can be done any way the author wishes -- using whatever tool(s) come to
hand, from cat to OpenOffice.org.
Second, this text has to have markup applied to it. ('tagging')
The rules governing how markup is applied are provided in standard SGML DTDs,
thus providing the opportunity to employ DTD-aware text processing and
validation methods.

The two activities may be combined into one simultaneous application of both,
depending on the author's degree of knowledge of markup technique, and
familiarity with the relevant DTD and its allowable entities; plus the
availability of suitable DTD-aware text processors.

Further, SGML-savvy authors may wish to write their own conformant DTDs.

The second stage: "transformation" is also a two-stage activity.
First the marked-up text must be passed through a processor to produce the
desired final form of processed text (pdf, html, xhtml, dvi, ps, tex, etc.).
Simultaneously, presentational formatting is applied to the document via the
application of a pre-defined style-sheet, to determine the final visual
appearance of the document within the chosen document type. (E.g. 'house
style' for a pdf sales document or catalogue, or html web page.)
Style sheets may be chosen from a library of pre-written elements; or written
from scratch by the document editor/publisher -- the latter demanding
appropriate knowledge of style sheet syntax.

The third stage: publication, demands only that a means be available to view or
otherwise present (i.e. 'publish') the document in its final form; e.g web-browser
for html document; graphical viewer for pdf document, etc. (Some means of
transferring screen output to printed hard-copy is also desirable.)

Of course, an overall fundamental requirement is for the availability of a
working GNU/Linux system with all necessary software tools installed, and to
which the editor/publisher has full user access.

Considerations concerning the storage and retrieval of documents in marked-up
text form, or full final presentation form -- whether in the guise of a full 
document library or database of discrete text elements -- are beyond the scope
of the present.


1. Text production tools
------------------------

a) command line
cat
ed / red
[edit] / editor
[pico] / nano
mcedit

b) under X
nedit
vi / vim / gvim
emacs / xemacs

c) text-processing apps
Abiword
LyX
OpenOffice.org

d) specialist markup apps
quanta
conglomerate
amaya

e) commercial wysiwyg editors
HoTMetaL
XMetaL


2. Transformation tools
-----------------------

i) DSSSL tools  (use .dsl stylesheets)
jade
openjade

ii) XSL tools  (use .xsl stylesheets)
xsltproc
saxon
xalan

'N'-conversion tools

xmlto


Exercises:
==========
Produce DocBook XML marked up text for, and then process, using your own 
preferred toolchain:

XML to:
- rtf
- tex
- pdf
- dvi
- ps
- html
- xhtml
- man
- info
- text


Produce DocBook SGML marked up text for, and then process, using your own 
preferred toolchain:

SGML to:
- xml
- rtf
- tex
- pdf
- dvi
- ps
- html
- man
- info


3. Publication tools
--------------------

gs
mozilla-firefox
OpenOffice.org
xdvi
xpdf


Links:
------
http://nwalsh.com/
http://docbook.org/
http://xml.org/
http://xsl.org/
http://xml.coverpages.org/

The latest version of this text may be found at:
      http://startext.demon.co.uk/SGMLdocs/
In the same directory will be found sample markup texts for students to 
experiment with.


Further reading:  (Google for 'em!)
----------------
DocBook-OpenJade-SGML-XML-HOWTO.pdf
DocBook-Demystification-HOWTO.pdf
DocBook-Install.pdf
DocBook_dbtexmath.pdf
LDP-Author_Guide.pdf


Glossary  (Google for 'em!)
--------
DocBook
DSSSL
DTD
psgml
SGML
TEI
XML
XSL


Index
-----
(Write it yourself.  Then mark up.)
============================================================================

-- 
Martin Wheeler   -   StarTEXT / AVALONIX - Glastonbury - BA6 9PH - England
mwheeler at startext.co.uk                http://www.startext.co.uk/mwheeler/
GPG pub key : 01269BEB  6CAD BFFB DB11 653E B1B7 C62B  AC93 0ED8 0126 9BEB
       - Share your knowledge. It's a way of achieving immortality. -