TeX vs. DocBook
sdieselil
I repost here my previous message. As I discovered texinfo is rather
old. So here is my question: what's better for writing documentation,
TeX or DocBook?
Joel Mayes
AFAIK texinfo != TeX
--
First they ignore you, | Gandhi, being prophetic about Linux.
then they laugh at |
then they fight you, | Joel Mayes
then you win. | Sourcemage GNU/Linux
Christopher Browne
> In article <169a7283.03030...@posting.google.com>, sdieselil wrote:
>> I repost here my previous message. As I discovered texinfo is rather
>> old. So here is my question: what's better for writing documentation,
>> TeX or DocBook?
>
> AFAIK texinfo != TeX
I expect that he probably grasps that they are distinct; that would be
why he cut the list to "TeX or DocBook".
I don't think there's a pat answer to that. I have generated a LOT of
both of them over the years, between a lot of academic work that
mostly used LaTeX, and more recent web work, using DocBook.
If the goal is to produce printed documentation where there will be
intense cross-referencing and perhaps even significant use of
mathematical equations, the TeX family is to be clearly preferred,
offering a mature tool set for producing professional typeset
material. (By the way: TeX is /older/ than texinfo, naturally falling
out of the fact that texinfo was built atop TeX... If age is a bad
thing, then TeX can't but be worse than texinfo...)
If the goal is to generate output in multiple forms, with HTML being a
vital format, and mathematical quality is of less importance, then
DocBook seems likely to be somewhat preferable.
Either will require some skill and effort to get totally "up to
speed," and a competent documentor should be able to produce decent
results using either.
--
output = reverse("gro.gultn@" "enworbbc")
http://cbbrowne.com/info/docbook.html
Rules of the Evil Overlord #228. "If the hero claims he wishes to
confess in public or to me personally, I will remind him that a
notarized deposition will serve just as well."
<http://www.eviloverlord.com/>
sdieselil
> Quoth Joel Mayes <jo...@invalid.invalid>:
> > In article <169a7283.03030...@posting.google.com>, sdieselil wrote:
> >> I repost here my previous message. As I discovered texinfo is rather
> >> old. So here is my question: what's better for writing documentation,
> >> TeX or DocBook?
> >
> > AFAIK texinfo != TeX
>
> I expect that he probably grasps that they are distinct; that would be
> why he cut the list to "TeX or DocBook".
>
> I don't think there's a pat answer to that. I have generated a LOT of
> both of them over the years, between a lot of academic work that
> mostly used LaTeX, and more recent web work, using DocBook.
>
> If the goal is to produce printed documentation where there will be
> intense cross-referencing and perhaps even significant use of
> mathematical equations, the TeX family is to be clearly preferred,
> offering a mature tool set for producing professional typeset
> material. (By the way: TeX is /older/ than texinfo, naturally falling
> out of the fact that texinfo was built atop TeX... If age is a bad
> thing, then TeX can't but be worse than texinfo...)
>
> If the goal is to generate output in multiple forms, with HTML being a
> vital format, and mathematical quality is of less importance, then
> DocBook seems likely to be somewhat preferable.
>
> Either will require some skill and effort to get totally "up to
> speed," and a competent documentor should be able to produce decent
> results using either.
I understood your point but I asked a bit different question. I know
that TeX is better for printed docs and for docs with a lot of math. I
also know that DocBook is better for HTML or XML docs. However, both
of them allow generating any form of output.
What I asked for is a comparison of these two completely different (in
syntax and in style) languages. Open to your opinions.
Homer Welch
Your original post said that you wanted to write
documentation for a program you wrote. Assuming it will run
in a unix environment, I think the first document should a
man page. Its the first place people look for information.
Man uses an old markup language called troff. Looking
at examples, it shouldn't be hard to create a man page
containing basic information on how to run the program and
you can provide a path to more sophisticated documentation,
if needed.
The program Info is sort of like a man page with hyper
links. The hyper links allow a more extensive document
without the bother of scrolling. I think this is the
texinfo you mentioned, and is not related to Knuth's TeX.
Both man and info were developed in a console environment to
be displayed online. Since man were based on troff, a
typesetting utility, it prints to paper satisfactorily
(maybe info, too. I've forgotten.)
TeX is a typesetting utility developed initially for
mathematics, but evolved into a general typesetting program.
It has a zillion operators allowing you to do whatever you
want. It is an addictive program that will send you to your
college's detox center to take a graphics design course.
The output of the program is a document called a dvi, for
device independence. That is usually turned into a
postscript document by running it through dvips. It can be
viewed in wysiwyg format using xdvi (for dvi) and ghostview
(for ps rendition.)
LaTex is a macro program based on TeX. It takes a lot of
the drudgery out of using TeX. Most TeX operators are
supported. Maybe what you want.
HTML is all the current rage, along with css, cascaded style
sheets. XML brings discipline to html if you are into such
things. The biggest advantage in this language is the
ability to use URL's to hypertext jump to other
documentation in the net, a very useful methodology.
What to use? It depends on how serious you are about the
presentation of your documentation. For reading a a
computer screen, html is fine. For paper output, I'd go
with TeX. Either way, you should create a man page.
Good luck,
Timothy Murphy
> I understood your point but I asked a bit different question. I know
> that TeX is better for printed docs and for docs with a lot of math. I
> also know that DocBook is better for HTML or XML docs. However, both
> of them allow generating any form of output.
>
> What I asked for is a comparison of these two completely different (in
> syntax and in style) languages. Open to your opinions.
I don't think it is worth considering plain TeX as opposed to LaTeX.
I don't think that LaTeX and DocBook _are_ that different.
If you've got lot of math you'll have to use LaTeX.
If not, XML/DocBook has particular advantage
if you want to output in different formats,
eg printing and on the web.
(LaTeX to PDF is easy with pdfLaTeX, but LaTeX to HTML is difficult.)
--
Timothy Murphy
e-mail: t...@birdsnest.maths.tcd.ie
tel: +353-86-233 6090
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
Christopher Browne
> I understood your point but I asked a bit different question. I know
> that TeX is better for printed docs and for docs with a lot of math. I
> also know that DocBook is better for HTML or XML docs. However, both
> of them allow generating any form of output.
> What I asked for is a comparison of these two completely different
> (in syntax and in style) languages. Open to your opinions.
You would probably want to use LaTeX, not TeX, and I don't think
there's much useful non-personal opinion to be had in comparing them.
There are aspects of all that I quite despise, between the real
arcaneness of nastier bits of TeX macrology (try modifying output
control and you'll see...), the irregularities of SGML, the irritating
verbosity and repetitiveness of XML... They all have some ugliness,
the mark of tools actually used.
I don't see it being terribly useful to try to compare them in detail.
They are big enough that we'll be guaranteed to be blind men clutching
at different extremities of the elephant, and hopefully nobody's
clutching too hard when I'm too near.
--
output = ("cbbrowne" "@ntlug.org")
http://cbbrowne.com/info/xml.html
Rules of the Evil Overlord #86. "I will make sure that my doomsday
device is up to code and properly grounded."
<http://www.eviloverlord.com/>
* Tong *
> sdieselil wrote:
>
> > I understood your point but I asked a bit different question. I know
> > that TeX is better for printed docs and for docs with a lot of math. I
> > also know that DocBook is better for HTML or XML docs. However, both
> > of them allow generating any form of output.
[...]
> if you want to output in different formats,
> eg printing and on the web.
> (LaTeX to PDF is easy with pdfLaTeX, but LaTeX to HTML is difficult.)
Yes, I think that's the point -- how many of formats can be
converted to/from them is more important than to language comparison
itself, and how easy they are. I don't know DocBook. For Latex, you
can check out
Tex Related Converters
http://xpt.sf.net/techdocs/Latex/TexRelatedConverters/frame.html
where you can see that it is pretty much every format can be
converted to/from Latex.
A side note, LaTeX to HTML is simple too.
--
Tong (remove underscore(s) to reply)
*niX Power Tools Project: http://xpt.sourceforge.net/
- All free contribution & collection
Timothy Murphy
> A side note, LaTeX to HTML is simple too.
I don't think that is true, unfortunately.
Only the simplest LaTeX documents using few if any packages
(and no mathematics)
can be translated easily into HTML.
If you actually want LaTeX and HTML
it is almost certainly simpler to write in XML
using DocBook or LinuxDoc,
and translate from this into LaTeX and HTML.
Lee Sau Dan
sdieselil> Hi I repost here my previous message. As I discovered
sdieselil> texinfo is rather old. So here is my question: what's
sdieselil> better for writing documentation, TeX or DocBook?
I would suggest texinfo. Don't feel scared just because it is old.
Paper is a millennium-old invention, but are you afraid of using it?
Exactly because texinfo is old, that I would suggest it. It's
*mature* and well understood. And there are a lot of tools readily
available for texinfo. You can easily convert the texinfo info source
to DVI, Postscript and of course Info. There are also mature tools to
convert texinfo into HTML. And since texinfo is old, it has evolved
into a very stable stage. The texinfo files you create today will
likely be still easily manipulable (with updated tools) after 10 years
without problems. Moreover, there are already lots of texinfo
available as examples for you to write yours.
DocBook is not bad. But it (esp. the XML variant) is still relatively
young, and hence evolving. Features that you use now may become
deprecated next year. While opensource formats/APIs/softwares tend to
have excellent backward-compatibility, maintaining things with
deprecated code is still a pain. Moreover, my feeling is that DocBook
tools, though available, are still not very mature. Thus, if you
choose DocBook, prepare to be revising your source documents from time
to time to catch up. You don't have to do that, but you may not be
able to resist the temptation! :) Having said that, I still want to
state some advantages of DocBook: being XML/SGML (attention: hype!),
being more extensible and capable than texinfo, closer to a printed
document (while texinfo strikes a balance between on-online viewing
and printing), being modern, etc.
Anyway, you're recommended to study both, and estimate what features
you'll need. If texinfo is already ENOUGH, then I would rather stay
with an older but highly mature format. (When DocBook matures, I
expect to see texinfo->DocBook converts around, available freely.) If
you NEED the new features offered by DocBook, then go with DocBook.
--
Lee Sau Dan 李守敦(Big5) ~{@nJX6X~}(HZ)
E-mail: dan...@informatik.uni-freiburg.de
Home page: http://www.informatik.uni-freiburg.de/~danlee