tlug: (La)TeX, SGML, or ... ?

[Matt Gushee <matt@example.com>]

Jonathan Byrne writes:

 > I need to pick a Linux/Unix-based tool to develop a site procedures
 > manual.  My criteria are that it should be easily editable (mostly by me,
 > but at some point by other members of the engineering department as well),
 > that it should be viewable and editable graphically,

In principle, I'd say SGML is the best tool for the job. It's
convertible to HTML, LaTeX, RTF, and other formats using existing
tools (personally, I don't care much for the HTML output ... you can
edit stylesheets to change that, but it doesn't sound like you have
the time). 

 > and if the format is
 > one for which a (good) convert-to-HTML tool exists, that's a plus.  At
 > this point, it seems that it will not need to be put into Japanese, so I'm
 > not concerned with language issues here.

At this point ... sounds a little like 'at this point we don't see any 
need for 4-digit date fields' ;-) Using SGML, if it turns out someday
that you do need Japanese, the change can be made very easily with no
changes to your DTD or existing documents ... though output formatting 
can still be a problem. With LaTeX, you would have to switch to a
Japanese tex program, which would probably require changes to the
markup.

 > would be better?  I know I could just do it in Applix, but I'm the only
 > person in the department who has it, so portability would be zero.

It hurts to say this (more than you know), but the docs would be
kind-of portable if you exported them in MS Word format. If you insist on
WYSIWYG, this may in fact be your best option.

 > A constraint is that I don't have time to learn to write markup language
 > files or anything just now, so I have to regard graphical editing of the
 > files as pretty important.

If you can write HTML, you can write SGML. You just have to learn a
new set of tags ... which, if you have an appropriate DTD, is easy
because the tags will be designed to fit the subject matter. So if you 
know the subject matter, learning the tags is a no-brainer. The catch, 
of course, is -- is there an appropriate DTD for you? DocBook is often
used for writing manuals, but DocBook is a huge,
everything-but-the-kitchen-sink affair, and you might be better off
using something a little more specific. Steve mentioned LinuxDoc, and
I agree you should check it out. It's very easy to learn (30
minutes?). If that doesn't meet your needs, the SGML/XML Home Page
<http://www.oasis-open.org/cover/sgml-xml.html> has pointers to all
kinds of DTDs and applications.

 > I would also like to use RCS for version
 > control if possible.

Not a problem as long as you use a text-based document format.


Stephen J. Turnbull writes:

 > I would say XML (a derivative of SGML) is probably the markup language 
 > of choice.  However, AFAIK there are no WYSIWYG editors for XML or any 
 > variant of SGML except HTML.  All SGML variants submit docilely to
 > [X]Emacs + psgml.el in my experience, which gives you menu-driven
 > editing but not graphical WYSIWYG.

There are definitely no native-to-Linux WYSIWYG editors, but I have a
feeling I've seen mention of something Java-based somewhere. If I saw
something like that and didn't try it out, it's just because I think
Java is crap ... but who knows, it might work. If such a thing indeed
exists, it's undoubtedly also listed at the above URL.

Now, I note that Jonathan didn't actually say WYSIWYG ... if you mean
'graphical' to include a GUI-based *structured* editor (i.e., rather
than seeing tags, you see the document in a prettified, easy-to-read
outline form), there's a thing called Thot which *seems* to do SGML
... though it's hard to tell from the docs just what sort of format it 
produces. The W3C's Amaya HTML editor is based on Thot. I'm not sure
I'd recommend it, though. There are apparently people who feel that
Thot/Amaya is a usable product. Personally, I consider them to be
alpha-quality software.

I'm also writing a structured editor, in Tcl/Tk (maybe switching to
Python/Tk) ... but I'm afraid it won't be ready in time for you. 

 >     jb> Also, I may eventually want to put screenshots into the
 >     jb> manual, but these will probably not be present in the first
 >     jb> version (s).
 > 
 > I don't know if LyX permits this, all of the other options do.

It does, though the images might have to be EPS files.

Hope you find something acceptable.

Matt Gushee
Oshamanbe, Hokkaido
-------------------------------------------------------------------
Next Nomikai: 14 January 1999, 19:30 Tengu TokyoEkiMae 03-3275-3691
*** it will will be Jan 14 (Thu), as Jan 15 (Fri) is a natl holiday
Next Technical Meeting: 13 February, 12:30               Place: TBD
-------------------------------------------------------------------
more info: http://tlug.linux.or.jp                     Sponsor: PHT