to SGML or not, that is the question

[Ralf Nolden]

Mark Coletti wrote:

Hi all ! I'm back !!! ;-) (together with a brandnew keyboard for writing
documentation ;-)

besides the tips of the others where to find sgmltools you will find
some good information how to write the documentation within the
html-pages provided with sgmltools. There are some tags that aren't
documented well and I had to search through the dtd itself to find them.
For writing style itself you can have a look at the kdevelop
documentation sgml masters that come with kdevelop and convert them to
ps over tex using sgml2latex.
 
> Side question: why SGML and not, say, XML?  And, yes, I know that XML
> is a sub-set of SGML.  (At least, so I've been told.  I confess I'm
> new to the SGML/XML game.)
I would say that a few years ago it has been the best and easiest
documentation tool for programmers- as much tags as C++ keywords ;-) so
it isn't hard to use. KDE 1.x uses it all over the place together with
ksgml2html adding a bit of a consistent KDE style to the html
documentation. Before writing documentation, I would consider asking
some docbook gurus of the kde documentation team because they know which
linuxdoc-sgml master style can be converted to docbook best for a KDE 2
app.
> 
> And lastly: can anyone recommend good SGML authoring tools besides a
> plain-ole text editor?
KDevelop ;-) because it contains an error finder for sgml errors just
like for the compiler. I had much trouble with unclosed tags myself, so
Sandy was so kind to implement that for me ;-) (Thanks Sandy ;-) 
For writing itself, linuxdoc-sgml is so easy that even I myself don't
prefer anything else than a text-editor and a 10-finger typing system
;-)


Bye,

Ralf