On 9/25/06, Sam Roberts <sroberts@xxxxxxxxxxxx> wrote:
On Mon, Sep 25, 2006 at 05:41:13PM -0400, John Gabriele wrote:
> * rdoc -- I like its simplicity, but I end up writing lots of html
Too simple for large documents.
Sam, thanks for the detailed reply.
Yes, I'm finding that rdoc is nice for code comments (which it was, of
course, designed for), but that it is indeed pretty limited for larger
standalone docs.
> * LaTeX -- Produces very beautiful output (*especially* for
> mathematics), but can be a bear learning to make it do things outside
> of the basics (i.e., syntax highlighting code, hyperlinks, adding
> graphics (like screenshots)). Easy stuff with LaTeX is easy, hard
> stuff is quite difficult (IMO).
Difficult, but good books around.
Yes. I've got a couple of them, and you just reminded me that I was
much less experienced the last time I read portions of them (*years*
ago). Maybe it's not as difficult as I'm remembering. :)
Good flexibility/power balance. Easy to version control, cause its
text-based (as all these are).
Best for outputting printed docs.
I agree. I've been to the bookstore with friends and gone, "Hey! Check
this book out. Look at the typesetting... This has gotta be TeX!".
(That's when they look at me like I need to get out more.)
I don't think its so good for
singlesource, multiple destination (html, windows help files, etc.).
Yeah... Re. converting to html, although there's some solutions out
there, they can be suboptimal (though I very much appreciate the hard
work that's gone into them over the years). Regarding that, and other
formats, the TeX faq as a few items:
http://www.tex.ac.uk/cgi-bin/texfaq2html?label=toascii
http://www.tex.ac.uk/cgi-bin/texfaq2html?label=LaTeX2HTML
http://www.tex.ac.uk/cgi-bin/texfaq2html?label=fmtconv (tex2rtf)
> * Textile (a la RedCloth) -- Very featureful. When I used it though,
Never used.
> * Markdown (a la BlueCloth) -- Looks great in a text editor. No tables
Never used.
In case you've never used these, they're translators that let you
write text files containing markup (which is often *asterisks*,
_underscores_, ### heading markers ###, [links](http://foo.com), and
so on) that's somewhat like rdoc.
I use Markdown for small web stuff, but I don't think I'd use it for
anything large.
> * POD -- I haven't written hardly any pod, but looking at Perl's docs
Very simple, like rdoc. Lots of output, many of them don't look so
great. I abuse it sometimes, but if you use it for other than what it
was intended, documenting (perl) code, you will hit walls hard and soon.
I read that Larry used it to write the Camel book but, IIRC, it took
some massaging to get it into something suitable for print.
> * DocBook -- very verbose. Also, the toolset seems a bit complicated
> to get used to. Not my thing.
You should look again.
You like emacs? Sgml/XML has GREAT editing modes. They parse the DTD,
and give you context sensitive completion of tags. I worked with a doc
guy who'd never used unix or emacs, and he learned and excelled in this
environment. Also, he wrote some great tutorials for lay people, see
below.
How does DocBook do with mathematical equations?
The tools were heavy, but very effective, particularly if you want to
do single source to many different outputs.
Right.
We had 4 or 5 output
formats, in varios combinations of book sets.
http://developers.cogentrts.com/cogent/prepdoc/book1.html
http://www.cogent.ca/index.html?http://www.cogent.ca/Info/Single_Source.html
http://www.cogent.ca/index.html?http://www.cogent.ca/Documentation.html
Thanks for those links.
Also, the tools are designed for technical documentation, and the markup
reflects that. function name, variable, code snippet. You get the idea.
I haven't worked with it for several years, through no choice of my own,
the company after downgraded from docbook to framemaker, and my current
company went even further down - we use ms word (a linux shop using
word...? who'd a thought it possible).
Oh my.
One place I worked at actually had MS Word docs under source control.
I know. I know.
> * Texinfo -- the GNU standard. Doesn't look too bad. Would need to
> learn more about bookmarks vs. cross-references, nodes, and some other
> info command stuff to use it well. Seems to work well with Emacs. ;)
> Also, I think you can get TeX-formatted math out of it (for, say,
> generating a pdf).
Texinfo is OK. Kindof oddball, IMO, and not so much control over output.
Does .info files of course, and OK html and print.
The Texinfo manual mentions that LaTeX is "much (much) larger" than Texinfo.
Kindof middle of the road. I'd consider real docs in it, but wouldn't in
the little "markup languages". Somehow even though I used it, I never
really liked it a lot.
> Which ones did I miss? Any strong likes or dislikes? If you had your
> choice, what format would you write most of your docs in?
How many docs, what size, what kind of output?
My own small docs and papers. Sometimes scientific in nature (hobby
stuff), other times docs for a software package (maybe some
tutorials). I haven't written anything large yet (that anyone else
would read), but want to use a tool that can scale up.
Though, for tiny web stuff, Markdown works well for me.
I'd also considered writing some Ruby documentation. Maybe even
something that might be useful to someone else!
I'd never use the simple markup languages for large documentation sets.
They are simple because capability was removed. Nice, until you need it!
:)
Latex is fast too get going with, pretty good markup and style
seperation, but pretty focussed on print (which it does very nicely).
By the way, I'm looking at the texinfo manual right now, and it's in
Computer Modern and looks quite nice.
For serious documentation (like manuals for all the s/w you will ever
make, in every possible output format, and with a good chance of parsing
rdoc output and generating docbook xml when you finally need printed
docs for you ruby libs, and it will be easy to write other doc
automation tools -- its xml!), I would go with docbook-xml. You will do
things that you couldn't do with $10,000 commercial tools.
Cheers,
Sam
Thanks again Sam. I'll probably have a look at docbook (and maybe
LaTeX) again, but only after reading some of the texinfo manual...
---John
| 
