[Asterisk-doc] LATEX or DocBook?

[Rainer Jochem]

--1yeeQ81UyVL57Vl7
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable


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

Both.
=20

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

Term of definiton what "easy to read" means:
     - People with knowledge of html will feel very comfortable with
       XML and so with Docbook
     - People who never ever have seen a Document description language:
       don't know which one is better -> This should be answered
       by someone else here.
     - A readable file also depends on the $EDITOR used by the author:
       when Leif gave me his docbook-version I almost fell from my
       chair ;) - Someonee was very generous with tabs and whitespaces
       to indent the tags and had obviously a very high screen
       resolution which resulted in vertical scrolling and
       linewrapping over here :-/

But generally speaking: If you write your "code" clean, again
both fulfill this point.

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

PS, PDF: no problem for both
HTML: seems to work with docbook (db2html) and with latex (latex2html)
      both didn't produce a very fancy output here, but I guess this
      can be improved. (Didn't use this functions before)


> Now, for some things I would like, but can live without.
>=20
>  4.  The ability to split the source document up into different files,
> such as one file per chapter.

Hmm... can live without this? Could get quite annoying IMO if half of
the book is finished and you then have to scroll several thousand
lines down to enter some text ;)

Splitting up might also be helpful in addition with CVS: if you just
have one big file where several people do changes in... dunno...

Well, at least it can be done with Latex.=20

Docbook? Dunno. Should be answered by someone else.


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

Well, things like papersize are no problem with tex - you just have to=20
replace the definition from e.g. a4paper to a5paper or letter or
whatever and you're done.

And I guess, it's again the same for docbook? Dunno.
=20
Regarding the numbering of chapters... hmm... they are numberd.
Or do I now miss something? I mean, I'm used to have a division like
   Part I blah
	Chapter 1 foo
		Section 1.1 bar
	Chapter 2 blubb

   Part II blo
   Appendix A Config
   Appendix B ...
etc.
At least for technical documentation that is.

Nevertheless I'm pretty sure that one can manipulate the counters
for the chapters e.g. from "Chapter 4 foo" to "Chapter IV foo" if
one wants this - almost every Latex-command can be re-defined, so
it should work although I have to admit that I've never tried to
manipulate the chapter-numbering as I've never needed to.
But manipulating headers, footers, list-numbering etc. is possible.

I hope that I did understand the question right :)


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

Ack.

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

Sure. Agreed.
Although one might ask if it is really neccessary to end a chapter
with </chapter>... If you write a book, it is quite obvious that at
the place where a new <chapter> or \chapter{foo} (for Latex) starts,
the old chapter is over ;)


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

Yep. This point should be answered by those who never have used both...

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

As mentioned above, this does not only depend on the language IMO, but=20
also (or more: mainly) on the editor you use: too much indention and
too much nested tags can be quite worse too. No matter how=20
"well-formatted" the document still is.

Speaking of Latex, you can have indenting and nested tags as well.
It doesn't make a difference for the interpreter if there are more
or less whitespaces in your document. So if you write proper=20
(Latex-)code, this should be possible with Latex too. This will=20
of course look a bit different to XML:

\begin{document}
\chapter{First chapter}=09
   \section{Introduction}
   Blah blah blah
	\subsection{foo}
	asdf jkl=F6 asdf jkl=F6 asdf jkl=F6
	\begin{itemize}
	   \item I am an item
	\end{itemize}

\chapter{Second chapter}
\end{document}




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

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

Might be - but I don't know docbook that much. But if you say so ;)


> > - As Latex has been around for a while there's plenty of=20
> >   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/

Humm... okay. To be honest, I've never tried to look for a *english*
Latex-Documentation: There's some pretty good Latex-Documentation in
german (279 pages of pdf) I use as my reference. Obviously this is
no help for you :)

But I just had a look in /usr/share/doc/tetex-doc/texmf on my machine=20
and I found some quite interesting and as I think good and useful=20
information about Latex - in english - ...
=2E.. - I just had a closer look at it... I'd say this is *the*=20
complete information you can get about tex. Have a look at it.
If you can't find it on your system, I've put a copy of it here:

   http://graphics.cs.uni-sb.de/~rainer/latexdoc.tgz



> 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.  :-) =20
>=20
> 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"?

PSTricks is a (La)TeX package which allow to use the major part of
PostScript capabilities inside (La)TeX.
see: http://www.tug.org/applications/PSTricks/
and: http://www.pstricks.de/examples.phtml

Of course this is the point where it starts getting challenging :)

What I wanted to say is: latex can do lots of things without=20
needing exterior software (e.g. for writing huge sets of=20
mathematical formulas). As I know Latex as a good friend for
producing scientifical publications this are some features
I really like and I doubt that docbook is able of this.

But on the other hand there's the question: do we need those
features? I don't know yet.



Uh-oh.... after having doubled the length of this email, I guess
it's time to hear the opinion of the other ones.


Greetings,
 Rainer


--=20
http://graphics.cs.uni-sb.de/VoIP/
--1yeeQ81UyVL57Vl7
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)

iD8DBQE/0iBoH/5+6U9F1qYRAgTwAKDEJWLIhGlVgY5YUPilxgPGWLN/7ACdEKS0
JUyKrUICJqCnDsibVRE8Ju0=
=KlEp
-----END PGP SIGNATURE-----

--1yeeQ81UyVL57Vl7--