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


1.  The package
consists of:

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


2.  Features
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  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












                                   - 2 -


   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.


3.  Requirements

To install it you need:
1  my  favorite  scheme compiler  bigloo (essential).  You  may obtain  the
   latest version from

   ftp://ftp.inria.fr/INRIA/Projects/icsla/Implementations
   There  is a plan to support guille,  but this will take a bit  of time I
   don't have by now.

2  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












                                   - 3 -



       http://www.jclark.com/sp.html


   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.

3  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.

4  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

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


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

6  I can recomment the psgml packages to edit your documents.
   get it from


       http://ftp.lysator.liu.se/pub/sgml/``''


   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.


4.  Distribution


   http:/www.inf.tu-dresden.de/ jw6


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












                                   - 4 -


descibes usage of SGML with SGML) I hopefully caught most of the bugs.


5.  COPYING

sdc is Copyright (C) 1995,1996 Joerg Wittenberger
This program  is free software;  you can  redistribute it and/or  modify it
under the terms of the GNU General  Public License as published by the Free
Software Foundation; version 2 dated June, 1991.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY  WARRANTY; without  even  the implied  warranty  of MERCHANTABILITY  or
FITNESS FOR  A PARTICULAR PURPOSE. See  the GNU General Public  License for
more details.
You should  have received a  copy of the  GNU General Public  License along
with this program; if not, write to the Free Software Foundation, Inc., 675
Mass Ave., Cambridge, MA 02139, USA.


   <joerg.wittenberger@inf.tu-dresden.de>



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


7.  Things to do

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

2  Use new epstogif as supplied from Sebastian Schnberg.

3  -R option to use diffenrent \figure env for LaTeX

4  Implement equations as in HTML-3 (This is in fact LaTeX :-)
5  a automatic glossary.

6  Implement <label> for info

7  Improve output for slides (no empty slides).

8  refine the A FAQ-DTD (due to user response)













                                   - 5 -


9  Refine the Brief (letter) formatting.

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

11 Merged indexes

12 Write the developers documentation
13 rewrite RTF output

14 move temp files to use $TMPDIR or /tmp with permission 0600