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

[Russell Bryant]

Luigi Rizzo wrote:
> 1. better check what the code does, see this in the output:  :)
> 
> 	+\begin{verbatim}
> 	+(null)
> 	+\end{verbatim}

Yeah, I messed that up.  It is fixed now, though.

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

I would be happy to move it all into the doc/tex directory, as well as
write up some README information.

> 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

Well, it's generated by CLI commands.  It seemed like a good idea at the
time, but it does make the implementation more complicated than it needs
to be.  A single command to dump all of the docs does make more sense.
It could still be implemented as a single Asterisk CLI command.  Then,
you could trigger the dump from the Asterisk CLI or from a shell:

   # asterisk -rx "core dumpdocs [format] [directory]"

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

Sure.  It does make sense to restrict the LaTeX formatting to a single
place in the code.  I don't really have any good ideas for post
processing so that we don't have to use {verbatim}, though.  Everything
is formatted in its own special way.  I would like to eventually come up
with a more expressive way to document all of these things than a big
blob of text so that it can then be extracted in more intelligent ways
into other formats.

Thanks for the feedback.  I'll work on incorporating these changes for
further review.  :)

-- 
Russell Bryant
Software Engineer
Digium, Inc.