[Asterisk-doc] LATEX or DocBook?

[Jared Smith]

OK, I've added some notes below...

On Fri, 2003-11-28 at 14:38, Rainer Jochem wrote:
> Hmm... vote or flamewar ;)
> 
No, let's consider it a "critical design review".  Let's (as
diplomatically as possible) discuss the pros and cons of each proposal,
and try to find something we're all happy with... I definitely think
it's worth it to spend some time in the beginning trying to do things
correctly and having a consensus.

Here are my major goals with the project.  I'll state them here in the
beginning, and then later we can debate which layout language better
fits the goals.

 1.  The source document should be a text-only ASCII file that can be
checked in/out of CVS (or some other revision-control system... I just
happen to be familiar with CVS.)

 2.  The source document should be easy to read and write by humans. 
(In my opinion, the easier it is to read and understand, the more people
will be willing to contribute to our project.)

 3.  The source document should produce at least Postscript and PDF
output that looks nice and clean and professional, and hopefully HTML
versions as well.

Now, for some things I would like, but can live without.

 4.  The ability to split the source document up into different files,
such as one file per chapter.

 5.  The ability to switch between different "style sheets", for lack of
a better term.  (For example, some people like their chapters, sections,
etc. numbered.  Others don't.  Some people may like the output on
8-1/2x11 paper... other's may want it in a smaller pocket-sized edition.
In other words, it would be nice to take the same source document and
produce different "styles" of output.)


Feel free to add to my list if there's something that's not there, or if
you disagree with any of my goals.  Now that those are out of the way,
I'll respond to some of the comments from the earlier emails.

>  
> 
> > Now, the thing I have a problem with LATEX is that it seems very
> > Linux'y, and DocBook seems to be less platform dependent.  Comments?
In theory, there should be tools for both latex and DocBook on both
platforms.  I only use Linux, so I can't really say what's available for
the Windows users.

> 
> - Both are plain ascii and can so be edited even with edit.com of 
>   good old DOS.
> 
Yes, thus the irrelevance of whether you prefer to use Linux or
Windows.  (See Goal #1) However, you may find it easier to convert the
ascii file to postscript and/or PDF easier on one platform or another.

> - Docbook uses XML which is IMO way overload and with all those
>   tags much more uncomfortable to keep track of the hierarchy
>   or nested things.
> 
I guess I like the XML for a couple of reasons.  First of all, I think
it's easier for people who are unexperienced with either latex or
DocBook to read and understand and write.  Anybody who's ever looked at
HTML source can pretty much understand a DocBook document just by
looking at the source... It's pretty obvious that <chapter> is the
beginning of the chapter and </chapter> is the end of the chapter. 
(Since I've never done anything more than a trivial term paper in latex,
I can't judge whether or not it's easier to *use*, but DocBook sure
looks like it would easier to *read and write* to a newbie.  See Goal
#2)

Second, XML has some built-in advantages.  First, it makes it easy to
check to see if the document is "well-formed".  (In the interest of
brevity, I'll let you google for well-formed if you're not familiar with
the term.)  I have no idea whatsoever if the Latex stuff has anything
similar. XML also supports XSL, which helps out with my goal #5.


> - Latex is ... well Latex :) It is different and perhaps from
>   the first point of view not that "easy" as Docbook which
>   obviously resembles well known Html etc. 
>   But Latex isn't difficult either - it's just a different
>   syntax but it is the same principle: Document description
>   language.
I'll agree with this statement, but again state that I think DocBook is
much easier to read (at least to the untrained eye) than Latex.

> 
> - Latex has some "specialities" like the need for escaping
>   special characters and it's styles where the whole 
>   page layout etc gets defined (but the latter is equal
>   with docbook). 
>   But if you know it, it is quite easy and well working with.
I think this can be said for both Latex and DocBook.

> 
> - As Latex has been around for a while there's plenty of 
>   documentation/tutorials/tricks/tips out there.
Yes, but there's not one good source for Latex documentation, at least
that I can find.  There seems to be little snippets here and there.  I
haven't found any online documentation for Latex that compares with the
"Definitive Guide to DocBook" at http://docbook.org/tdg/
> 
> - Latex can quite easy split a document over different files
>   which makes it comfortable for larger documents
I'm hoping that this is possible under DocBook!  I'm pretty sure it's
possible, I just haven't tried to do it yet.

> 
> - Every good editor provides a Latex mode with appropriate
>   syntax highlighting.
Yes, and even crummy editors have XML syntax highlighting.  :-)

> 
> - One can do quite a bunch of things with Latex and pstricks
One can do quite a bunch of things with duct tape, bailing twine, and
chicken wire too... I once used chicken wire and bailing twine to hold
the headlight in my car until I got a new car.  :-)  

Actually, I totally missed the point of this statement.  What exactly
are the things you are proposing to do with Latex and pstricks?  Is
pstricks a program, or is it short for "Postscript tricks"?

> As one might already have guessed, I'm someone who likes
> Latex very much :) 
> First of all because of the features, but to be honest also
> of the fact that I'm used to it and quite lazy to change
> a running system...
Yup... I guessed that.  And I'm coming from the opposite camp... I've
only used Latex two or three times, and hated it.  (Thank goodness for
Lyx, even if it's a crummy program!)  I originally proposed using
DocBook because I had played around with it a little, and found the
syntax to be refreshingly easier than Latex. 

Don't get me wrong, I'm against doing the project in Latex if that's the
best tool for the job.  I just want to get this hammered out up-front,
so that we don't end up with two competing projects down the road, just
because of egos and personal preference.  

Like I stated earlier, I really want to have an in-depth discussion on
which formatting language to go with, so feel free to write back and
tell me I'm wrong!  

Jared