[asterisk-dev] [asterisk-commits] russell: trunk r72932 - in /trunk/doc: ast_agi_commands.tex asterisk.tex

[Luigi Rizzo]

On Mon, Jul 02, 2007 at 12:52:52PM -0700, Luigi Rizzo wrote:
> On Mon, Jul 02, 2007 at 07:31:27PM -0000, SVN commits to the Asterisk project wrote:
> > Author: russell
> > Date: Mon Jul  2 14:31:26 2007
> > New Revision: 72932
> > 
> > URL: http://svn.digium.com/view/asterisk?view=rev&rev=72932
> > Log:
> > Add AGI commands to the documentation
> 
> I have a few comments on this and related commits:
> 
> 1. better check what the code does, see this in the output:  :)
> 
> 	+\begin{verbatim}
> 	+(null)
> 	+\end{verbatim}
> 
> 2. it might be better to put all this latex stuff into its own
>    directory, e.g. doc/tex/ or the like, to avoid cluttering doc/
>    with all this stuff. doc/tex/ could also contain a Makefile and
>    a README on how to regenerate-rebuild the documentation, and also
>    what to add in the source code to generate the latex (formatting
>    conventions and the like).
> 
> 3. I am not sure I understand why the latex is generated through
>    manager commands. While i may see a reason to do it at runtime,
>    perhaps because certain commands are dynamically created etc,
>    I would expect only one command-line switch like
> 	asterisk --dump-doc [format[:directory]]
>    which generates the latex and terminates.
> 	This would make all the completion etc redudant, and simplify
>    the implementation
> 
> 4. Irrespective of item #3, there seems to be a lot of commonality
>    in the code to generate the latex (and even more should you decide
>    do to a bit more postprocessing on the CLI output to show something
>    better looking than {verbatim} text.
>    So it might be good to define a wrapper function that takes a tuple
>    <style - title - body > and produces the required output.
>    This would also simplify the generation in other formats.
> 
> What do you think ?

(apart from the fact that i should i have trimmed the rest of the
original post, sorry about that!)

	cheers
	luigi