<!-- -*-jfw-sgml-*- -->
<!doctype document public "-//JFW//DTD Document//EN"[
<!ENTITY sdc "sdc" >
<!ENTITY cr SYSTEM "copyright.text" >
]>

<document
face="nidx 1c"
author="J&oe;rg Wittenberger"
>README for &sdc;

&sdc; is a well featured,
free system aiming to make SGML suitable for day to day use.
It's in a "production state" now
and proved for large documentation.

With &sdc; it is really simple to write technical documentation,
reports, books, letters, man pages,
or
prepare talks and classes (with slides and hand outs).
You can include some graphic
(made with other tools, e.g., xfig, tgif or anything creating EPS-Files)
or other special data representation (e.g., tlb/roff tables)
and so on with ease.

Whatever you do,
while writing you never have to worry
what the final result will look like.
When done,
you convert your writing into the desired target format by &sdc;
and promised: it will look <em/at least/ reasonable.

The goal of &sdc; is
to be author friendly,
easy to use without the need of special editors
and to hide as much of the backend as possible.
For the sake of the latter extremly funny features
of the one or other backend are not supported.
Or at least not in a portable way.

The version 0.7 (sdc-1.0) is a mayor rewrite.
Internals have changed to allow
for more flexibility and arbitrary changes to the document
structure. While it should not do, that might affect some (a few)
documents.

It turned out long ago, that some shells have an internal command with
the same name as the original -- typeset. Therefor I'm looking for a
new name.  If you have an idea: PLEASE mail me.

<sect>The package

consists of:

<list>
<o>a executable (parser/formater)

<o>a library of document type definitions (DTD'S)

<o>a set of files describing the formatting for the various output
formats (currently LaTeX, PostSript, HTML, Info, roff -man, ASCII,
limited RTF and slides). RTF is still supported the old way.

<o> some scrips to do automatic conversion of graphic and other
notations

</list>

<sect>Features

<list>
<o> The whole system is written in the aim to be author friendly. The
DTD's are very easy to use. (LaTeX, QUERTZ, TeXInfo or HTML are
<em/much/ more complicated.)

For SGML experts: We use mixed content model almost everywhere. While
you can type text at any place it's meaning is ambigous
sometimes. Therefor we parse internaly a second time and format as if
we had a element content most of the time.

<o> Backend formaters are completely hidden. Don't worry about any
'special' characters but the two introduced trough SGML (< and &).

<o> Multi Language support (current english and german) including
automatic hyphenation (for PostScript). Custumization to support
danish, dutch, finnish, french, norwegian, spanish and swedish should
be a matter of minutes. (Not done because I can't test it.)

<o> Support for system notations. (xfig, tgif, roff/tbl, LaTeX, lout)
Suitable for converting entities like pictures and complicated
formulas into a format accepted by the target format.

<o> DTD's for simple documents, reports, books, manpages and
DIN-letters. (The latter is in german and easy enough to be used by
secretaries knowing nothing about computers and SGML). Adding new
DTD's is quite simple and strait forward.  Book support partially
done.

<o> Required markup is minimized.

<o> Support of bibliography databases. (Database is SGML too.)

<o> Automated creation of sorted indices.

<o> Automagical insertion of standard text parts (like bibliography
[from referenced items of the currently used databases], content and
cross reference text).

<o> Support for literate programing.

<o> Adding new output formats is fairly easy. (roff -ms and RTF will be
the next targets)

<o> Frontend SGML-parser is sgmls/nsgmls, thus you can use everything
these understand.

<o> Easy to extend through Scheme.
</list>

<sect>Requirements

To install it you need:

<enum>
<o> my favorite scheme compiler bigloo (essential).  You may obtain
the latest version from
<nl>
<verb>
ftp://ftp.inria.fr/INRIA/Projects/icsla/Implementations
</verb>

There is a plan to support guille, but this will take a bit of time I
don't have by now.

<o>sgmls version 1.1.91 or above or nsgmls (essential) which is used
as the SGML-parser (we use features not in V 1.1). If you have C++
available you can use nsgmls instead. It comes with sp from

<quote>
http://www.jclark.com/sp.html
</quote>

There is also sgmls version 1.1.91 available which doesn't need this
******* C++. Otherwise I can sent sgmls 1.1.91 out by mail. Just drop
me a note.

<o>LaTeX (semi optional) serving one backend which looks nicer
than the Lout (especially for math formulas) but is harder to deal
with.  Note that to include eps pictures &sdc; relies on epsfig.sty
respectivly the graphics package.

<o>Lout version 3.05 (or above, semi optional) which is the (hidden)
PostScript and ASCII formatter (much easier to program than LaTeX).
You may obtain the latest Version from

<quote>
ftp://ftp.cs.su.oz.au/jeff (original ftp site) or <nl>
ftp://ftp.inria.fr:/textproc
</quote>

<o>if you want automatic figure handling as it comes, you'll need
tools like tgif, xfig, ghostscript and pnm tools.

<o>I can recomment the psgml packages
   to edit your documents.

   get it from
   <quote>
   http://ftp.lysator.liu.se/pub/sgml/"
   </quote>

   But with the little amount of markup it's not nessesary.
   I use a supplied mode with some highlighting,
   which is quite a hack, but the hilit is useful.

</enum>

<sect>Distribution

<quote>
http:/www.inf.tu-dresden.de/~jw6
</quote>

For usage see the intro.ps.  Unfortunatly it's not too detailed, but
comparing source and output might serve it's purpose for everyone.
Cause it's probably one of the most complicated documents you can
write (it descibes usage of SGML with SGML) I hopefully caught most of
the bugs.

<sect>COPYING

&cr;

<quote>
&lt;joerg.wittenberger@inf.tu-dresden.de>
</quote>

<sect>Changes

See the Changes.sgml or the approbriate section in the introduction.

<sect>Things to do

<enum>
<o>Add a note in the doc's about the `id'-attribute of sect's etc.
   especially their use in the info target.

<o>Use new epstogif as supplied from Sebastian Schnberg.

<o>-R option to use diffenrent \figure env for LaTeX

<o>Implement equations as in HTML-3 (This is in fact LaTeX :-)

<o>a automatic glossary.

<o>Implement &lt;label> for info

<o>Improve output for slides (no empty slides).

<o>refine the A FAQ-DTD (due to user response)

<o>Refine the Brief (letter) formatting.

<o>LaTeX code for verb-elements is still subotpimal. It ought to break
full lines. Anybody knows how to achieve this?

<o>Merged indexes

<o>Write the developers documentation

<o>rewrite RTF output

<o>move temp files to use $TMPDIR or /tmp with permission 0600

</enum>