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

[Tzafrir Cohen]

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

Still, for the build system we need a way to extract the documentation
of all the AGI commands. Even those currently disabled, right?

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

5. The commands dump to a hard-wired file name. Allow declaring a target
   filename with 'into FILENAME'?

   It should be the responsibility of the caller to provide a temporary
   file name and to clean up.

6. The SVN now includes the outputs of those commands. But that output
   depends on the modules you happened to build on your system when you
   updated the file.

-- 
               Tzafrir Cohen       
icq#16849755                    jabber:tzafrir at jabber.org
+972-50-7952406           mailto:tzafrir.cohen at xorcom.com       
http://www.xorcom.com  iax:guest at local.xorcom.com/tzafrir