The obvious counter-question
to a lot of the comments here
is simply "what do you want it for?"
When responding to
a posting like the one
which started this whole
discussion, I think
it should be fairly
evident that
we're talking about
a solution which
is flexible and scalable
enough to be useful
even for small documents
like manual pages,
and yet provide the
power to do
technically complex
documentation with
pictures, cross-references,
multiple volumes,
possibly multiple
concurrent versions
(a "lite" document
and the "real thing"
from the same
sources, perhaps).
I don't suppose
anybody here would
have experience
with professional
tools like Arbortext /
Documation / whatchamacallit,
at least enough
to comment
on where they
fit into
the big picture?
My own list of requirements
goes something like this --
Flexible viewing and editing
It should be possible
to produce different
views of the text
(perhaps by piping
the source file
through a script
or something).
I should have control
over what parts of text
and how much of the
metadata I see
(seeing e.g. all my own
comments and notes is
an absolute requirement;
in addition,
outlining is nice,
conditional inclusion
is nice).
I should not have to
use a particular application
in order to change
the text or the
metadata
(i.e. I should be able to
produce parts of the
text by running a
script, or I should be
able to use my own
source format and
a formatter which
produces what the
typesetting/whatever
system wants to see.
I should be able to
get sensible differences
from a version control
system, and easily
merge stuff from one
version into another).
All of this points to
an ASCII-based format,
and Emacs as a pretty
darn good primary
editing tool.
Also, it pretty much
rules out any
WYSIWYG editor.
(There is no such thing
as a "WYSIWYG editor"
because editing is
an activity where,
by definition, you
are not out to get
what you see, but
rather, to create a
file which is
meaningful both to
you and to the
computer.
Using a word
processor for this
is completely
misdirected.)
Reasonable output
Decent hardcopy.
This used to be
very hard to
come by.
troff is the
only system
I've tried
which
procuces remotely
acceptable output
without tweaking.
TeX used to produce
pretty ugly output,
but I suppose that
has improved
(but you still
need to tweak
in order to
get rid of
Computer Modern,
n'est-ce pas?)
Decent HTML.
If you use
HTML as your
actual format,
this is a
no-brainer.
But most documentation
systems nowadays
can produce
more or less
palatable
HTML.
Some sort of
hypertext architecture
is required
in order to get
the most out of
on-line renderings.
But HTML is
of course not
the only game
in town.
Half-decent presentations.
This is hard.
I've had some
good experience
with HTML slides
from the W3C
SlideMaker tool,
but it's
very very
pedestrian.
I suppose PDF is
something a lot of
sites require
nowadays,
although it's
not something
I particularly
care about.
(In fact, I
hate PDF.)
The future trend here
is probably XML
with tools for
producing
HTML and troff
output.
(I don't know
of any tool which
does xxxML to
troff, any
pointers?)
Text, code, and image modularity and integration
Including images
and code snippets
should be trivial.
Keeping them in
separate files
should not be
hard or clumsy.
Conversely,
being able to do
simple images
(and code, of course)
in-line would be
very nice.
(Good old troff
with pic macros
is pretty usable,
if you can find
somebody to
teach you...)
I've looked at various
Literate Programming
tools (noweb, POD, etc)
and they all fail on
some other criteria
of mine, although I
think the idea is
very good indeed.
My first gripe with
these is that
some sort of
#include facility
is a must,
because the documentation
file structure
should be modular
just like the
code structure.
(Anybody know
of a LitProg
system which
doesn't have
this limitation?
Also it should
preferably not
require TeX and/or
some particular
programming
language; I want
to be able to
document code
in any
programming
language!)
Mathematical formulas
are not important
in my work, but
if they are important
to you,
TeX suddenly gets to
seem attractive
(at least until
MathML takes off).
Clear separation between content and presentation
This is where
I think TeX fails.
I should not have to
include instructions
for italic correction
or hyphenation hints
smack dab in the
text itself.
(Is this a
misdirected
comment with
newer versions?)
Style sheets
are pretty much
a must for
anything
more complex
than five to
ten pages.
Again, I have not
found any tools
that really
fit the bill,
but it looks to me
like XML is
pretty much the
answer, longer term.
Low overhead in expression
My favorite here
is definitely POD.
HTML and XML
have a terrible
signal-to-noise
ratio.
They're okay for
readers, but
writing raw
xxxML is
too clumsy for me.
I guess
it's safe to say
that
troff
-- with macros,
or without --
is about as
user friendly
as assembly
language...
I'm afraid this
came out less
structured
than I'd like it
to be,
but it's
hopefully
useful to
somebody
nevertheless.
(I think it's
pretty safe to
blame the
ridiculously
small form
submission box,
and the inadequate
form editor in
my web browser.
I did produce
a first draft
in Emacs,
but then I
had to make
modifications...)
Slashdot Mirror
The obvious counter-question to a lot of the comments here is simply "what do you want it for?"
When responding to a posting like the one which started this whole discussion, I think it should be fairly evident that we're talking about a solution which is flexible and scalable enough to be useful even for small documents like manual pages, and yet provide the power to do technically complex documentation with pictures, cross-references, multiple volumes, possibly multiple concurrent versions (a "lite" document and the "real thing" from the same sources, perhaps).
I don't suppose anybody here would have experience with professional tools like Arbortext / Documation / whatchamacallit, at least enough to comment on where they fit into the big picture?
My own list of requirements goes something like this --
All of this points to an ASCII-based format, and Emacs as a pretty darn good primary editing tool.
Also, it pretty much rules out any WYSIWYG editor. (There is no such thing as a "WYSIWYG editor" because editing is an activity where, by definition, you are not out to get what you see, but rather, to create a file which is meaningful both to you and to the computer. Using a word processor for this is completely misdirected.)
I suppose PDF is something a lot of sites require nowadays, although it's not something I particularly care about. (In fact, I hate PDF.)
The future trend here is probably XML with tools for producing HTML and troff output. (I don't know of any tool which does xxxML to troff, any pointers?)
Including images and code snippets should be trivial. Keeping them in separate files should not be hard or clumsy. Conversely, being able to do simple images (and code, of course) in-line would be very nice. (Good old troff with pic macros is pretty usable, if you can find somebody to teach you...)
I've looked at various Literate Programming tools (noweb, POD, etc) and they all fail on some other criteria of mine, although I think the idea is very good indeed. My first gripe with these is that some sort of #include facility is a must, because the documentation file structure should be modular just like the code structure. (Anybody know of a LitProg system which doesn't have this limitation? Also it should preferably not require TeX and/or some particular programming language; I want to be able to document code in any programming language!)
Mathematical formulas are not important in my work, but if they are important to you, TeX suddenly gets to seem attractive (at least until MathML takes off).
This is where I think TeX fails. I should not have to include instructions for italic correction or hyphenation hints smack dab in the text itself. (Is this a misdirected comment with newer versions?)
Style sheets are pretty much a must for anything more complex than five to ten pages.
Again, I have not found any tools that really fit the bill, but it looks to me like XML is pretty much the answer, longer term.
My favorite here is definitely POD. HTML and XML have a terrible signal-to-noise ratio. They're okay for readers, but writing raw xxxML is too clumsy for me.
I guess it's safe to say that troff -- with macros, or without -- is about as user friendly as assembly language...
I'm afraid this came out less structured than I'd like it to be, but it's hopefully useful to somebody nevertheless. (I think it's pretty safe to blame the ridiculously small form submission box, and the inadequate form editor in my web browser. I did produce a first draft in Emacs, but then I had to make modifications...)