[asterisk-dev] latex doc files

[Derek Smithies]

Hi,
 I am not sure lout is a reasonable option.

>From the lout web page at sourceforge,

Be Aware: PDF backend is broken since 3.21 and was under reconstruction! 
In 3.24 it's more or less ok, but recently introduced glyph composition 
feature is not yet supported. Jeff officially declared PDF backend 
desupported in 3.25.)

native pdf support is a "nice to have feature". yes, we can generate ps 
with lout, then turn the ps to pdf, but the output is not as nice.

========================

lout is not on every box, or every distribution. The latex, latex2html, 
doxygen, etc tools are in every distribution.

========================
latex generates high quality typesetting also. Sufficiently high that 
latex output is production ready, i.e. good enough for journals/books to 
use directly.

I do not know if lout is to this standard.

=======================
The key to generating quality doc files is (in my view) not the 
documentation language. The key is the content of the docs.

Things like removing pages such as:
http://www.asteriskdocs.org/modules/tinycontent/content/docbook/current/docs-html/x258.html
   (getting  asterisk from cvs)

or immproving/removing comments like:
typedef struct mxml_custom_s           /**** An XML custom value. ****/

 the type name of the variable is such that the comment adds no value. 
Thus, the comment should either be removed (it has zero value at the 
moment) or improved (to say what data could/would be held in the 
variable).


Derek.

====================================================================
 On Sat, 19 May 2007, Dylan VanHerpen wrote:

> Then how about lout:
> 
> http://lout.sourceforge.net
> 
> Here is a list of Lout features:
> 
>    * High-quality typesetting
>    * Comes with predefined styles for books, technical reports, etc
>    * Supports tables, diagrams
>    * Automatic table of content, index, glossary, etc
>    * Extensible and customisable language
>    * Supports many languages (i18n)
>    * Small (2 Mb)
>    * Mature (Lout was created in the 90s)
> 
> To get a better idea, browse the user guide (PDF):
> http://www.it.usyd.edu.au/~jeff/loutuser.ps
> 
> Check out chapter 9. With Lout it is very easy to create flowcharts,
> syntax diagrams, trees, labels, etc.
> 
> Regards,
> 
> Dylan.
> 
> 
> 
> On 4/9/07, Olle E Johansson <olle at voop.com> wrote:
> > I am a bit concerned about the addition of Latex to our toolset.
> >
> > It's hard to get developers that submit code to add doxygen comments.
> > It's even harder
> > to ask them to write documentation.
> >
> > To add Latex knowledge to the requirements, will make it even worse.
> > That means that
> > we will shift all the documentation production and management to a
> > small group of
> > contributors.
> >
> > I understand the need for more layout options that .txt files. html
> > could handle that
> > *and* still work with Doxygen, that we use today. I don't think .tex
> > files can be handled
> > by Doxygen the way we include .txt files today.
> >
> > It's not that I don't appreciate Russell's efforts to produce better
> > docs. It's about
> > the format and tool used.
> >
> > /O
> > _______________________________________________
> > --Bandwidth and Colocation provided by Easynews.com --
> >
> > asterisk-dev mailing list
> > To UNSUBSCRIBE or update options visit:
> >    http://lists.digium.com/mailman/listinfo/asterisk-dev
> >
> _______________________________________________
> --Bandwidth and Colocation provided by Easynews.com --
> 
> asterisk-dev mailing list
> To UNSUBSCRIBE or update options visit:
>   http://lists.digium.com/mailman/listinfo/asterisk-dev
> 
> 

-- 
Derek Smithies Ph.D.
IndraNet Technologies Ltd.
Email: derek at indranet.co.nz
ph +64 3 365 6485
Web: http://www.indranet-technologies.com/