TeX vs. DocBook

TeX vs. DocBook

Post by sdiesel » Sat, 08 Mar 2003 07:46:43



Hi

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?

 
 
 

TeX vs. DocBook

Post by Joel Maye » Sat, 08 Mar 2003 09:57:39



> Hi

> 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

--
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

 
 
 

TeX vs. DocBook

Post by Christopher Brown » Sat, 08 Mar 2003 14:13:15




>> 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.
--

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/>

 
 
 

TeX vs. DocBook

Post by sdiesel » Sun, 09 Mar 2003 00:55:57





> >> 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.

 
 
 

TeX vs. DocBook

Post by Homer Welc » Sun, 09 Mar 2003 07:36:56



> Hi

> 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?

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 *ive 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,

 
 
 

TeX vs. DocBook

Post by Timothy Murph » Sun, 09 Mar 2003 09:01:16



> 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*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*to HTML is difficult.)

--
Timothy Murphy  

tel: +353-86-233 6090
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland

 
 
 

TeX vs. DocBook

Post by Christopher Brown » Sun, 09 Mar 2003 12:18:13



Quote:> 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.
--

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/>

 
 
 

TeX vs. DocBook

Post by * Tong » Mon, 10 Mar 2003 11:38:26




> > 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*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://www.veryComputer.com/

where you can see that it is pretty much every format can be
converted to/from Latex.

A side note,*to HTML is simple too.

--
Tong (remove underscore(s) to reply)
  *niX Power Tools Project: http://www.veryComputer.com/
  - All free contribution & collection

 
 
 

TeX vs. DocBook

Post by Timothy Murph » Mon, 10 Mar 2003 21:31:18



> A side note,*to HTML is simple too.

I don't think that is true, unfortunately.
Only the simplest*documents using few if any packages
(and no mathematics)
can be translated easily into HTML.

If you actually want*and HTML
it is almost certainly simpler to write in XML
using DocBook or LinuxDoc,
and translate from this into*and HTML.

--
Timothy Murphy  

tel: +353-86-233 6090
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland

 
 
 

TeX vs. DocBook

Post by Lee Sau Da » Tue, 11 Mar 2003 16:33:00


    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.

--


Home page: http://www.informatik.uni-freiburg.de/~danlee

 
 
 

1. Texinfo vs. TeX vs. DocBook

Hi

I wrote my own program and want to write normal documentation for it. I
want to write it in a some kind of formatting language and then produce
PDF (or PS) and HTML variants from it. As far as I know there are 3 big
formatting languages: TeX, Texinfo and DocBook (which is actually based
on XML or SGML).

What language should I choose? What are pros and cons of each of them?
Are there articles with detailed comparison of these languages?

2. tracing X events--focus, unfocus, mouse movement, etc.

3. Linux vs OS2 vs NT vs Win95 vs Multics vs PDP11 vs BSD geeks

4. openssh can't dlopen libdigestmd5.so

5. ps->tex html->tex?

6. QPopper and Sendmail

7. AUC-TeX Emacs package added to SLS TeX files

8. Cutting & Pasting

9. Where to install TeX input files in TeX-related rpm package

10. tex(only root can do tex), revised

11. TeX usage and TeX errors

12. Perfomance: tar vs ftp vs rsync vs cp vs ?

13. Slackware vs SuSE vs Debian vs Redhat vs ....