documentation system

["J. F. Wittenberger" <jerry pfirsich compot com>]

-----BEGIN PGP SIGNED MESSAGE-----


Hi forks,

I'm following the gnome project, because I believe it's a great
project.  I'm personally definitly not in the GUI bussiness, that's
why I can't contribute too much.

But for the documentation project I could possibly contribute
something:

I did quite a resonable document system long ago.  It's in
productional use for years now doing everything I need: letters,
reports, books, slides and literate programming.  It was originally
inspired by the missing features from quertz and linux-doc.

Not hiding the caveats I must admit that it lacks any user interface,
that is anything producing sgml does.  Instead it fits quite well into
Makefiles.

It features it's own DTD's, which have been designed with authors
hacking sgml by hand in mind (That has been the main reason not to use
quertz, linux-doc and docbook) producing ps (via LaTeX or lout), man
pages, html (which needs some work to comply with 4.0), plain text and
gnu info.  If the target format supports figures those are handled
automatically.  You can even have inlined code of different notations,
e. g., mixes of tbl, latex, lout, tgif, xfig or postscript code.

The documentation is available at
http://pfirsich.compot.com/~jerry/doc/sdc/

I've thrown in a quick hack to support linux-doc.  Supporting docbook
would require to have a closer look at it and probably use a simillar
trick or some more extensions.  If you forks where to use it I'm ready
to take my time.

For the literate programming idea:  this would either have to go the
other way around, not extracting the doc strings from the source code,
but writing a sgml document for that which could include the source
using the literate programming feature like that:

<literate file="source.whatever">
  if( test ) ...
</literate>

(the docs include an example for that; the whole bunch of figure
handling is done that way) or use smth like pearl (as proposed) and
extract a sgml doc from the source code.

I'm waiting for your comments on that...

As I'm writing I think I ask for some more comments.  I recently
started another project, which is not ready for public consumtion.

It's sort of a web integrated group ware system giving you (some day)
2way links, never changing documents (as well as those up to date),
garbage colletcted pages, data replication.  It can also be viewed as
cgi for everybody because it allows to create pages with secure
cgi-alike scripts (no file access except tmp files).  Despide the fact
that installing a new version of the es shell broke everything it's
documentation (which need questions to be improved) and code is
avaliable at http://pfirsich.compot.com/~jerry/software/webstar/doc/

/Jerry


-----BEGIN PGP SIGNATURE-----
Version: 2.6.3ia
Charset: noconv
Comment: Processed by Mailcrypt 3.4, an Emacs/PGP interface

iQCVAwUBNNtzZH97iaGvWchtAQFdeAP+IH7O8H3zJuEcNq2BdKSJxHtaOZ3Z0GPz
FJvttZ+NDE+i/ym8+1OvdwcJBN66h69JQ5CQJFfFSgIiCyOJNe3ETU9Aq1l6jH9u
h2JXQzhlai9n7y0uywf11KGHpupV4wXr27Dbgz7NEczC/2+tSNFSsiZYn1JTz7TT
GxN6Gx2PcV8=
=It8A
-----END PGP SIGNATURE-----