[asterisk-dev] Feedback requested for future 1.6 API documentation

[Sam Liddicott]

I suggest tbook, which has a very simple XML DTD - and I mean VERY 
simple, it looks a bit like html 0.1 but generates lovely documents as 
latex, pdf, html, ..., ...

http://tbookdtd.sourceforge.net/

I'm using it for production of automated test reports, with graphs and 
charts, etc.

Sam

* Tzafrir Cohen wrote, On 02/03/09 13:44:
> On Sun, Mar 01, 2009 at 11:47:17PM -0600, Jeff Peeler wrote:
>   
>> Last year in May I authored a document detailing all of the API 
>> changes from 1.4 to 1.6.0 (doc/api-1.6.0-changes.odt). At that time 
>> it was thought that we would be able to keep the API frozen for all 
>> releases after 1.6.0. This rigid requirement has turned out to be too 
>> hard to accommodate. The plan now is to continue documenting the API 
>> changes from one release to the next. This decision poses a few 
>> questions:
>>
>>     
>
>   
>> What format should be used? Both the file format and the content 
>> layout should be considered. I originally chose an OpenDocument 
>> text simply because it wasn't planned to ever be updated. I encourage 
>> everybody to take a look at the existing document to get an idea of 
>> what might should be included.
>>     
>
> LaTeX example:
>
>
> %%%%%%%%
> %%%%%%%% Uglyness you shouldn't care about:
> %%%%%%%%
> \documentclass{article}
> \newcommand{\old}{1.4}
> \newcommand{\new}{1.6}
> \newcommand{\oldexheader}{\subsection{\old\ Example}}
> \newcommand{\newexheader}{\subsection{\new\ Example}}
> % Maybe format as a table like in the ODF?
> \newcommand{funcdiff}[6]{%
> \section{#1}%
> \paragraph*{Location}{\tt #2}%
> \paragraph*{\old\ Prototype}{\tt #3}%
> \paragraph*{\new\ Prototype}{\tt #4}%
> \paragraph*{Change Explained}#5%
> \paragraph*{New Types or Variables}#6%
> }
>
> \begin{document}
>
> \tableofcontents
>
> %%%%%%
> %%%%%% The part that actually gets edited:
> %%%%%%
>
> \funcdiff{ast\_agi\_register}
>   {/include/asterisk/agi.h}
>   {int ast\_agi\_register(agi\_command *cmd);}
>   {int ast\_agi\_register(struct ast\_module *mod, agi\_command *cmd);}
>   {module parameter added to keep track which module registered the AGI %
>     command as well as the reference count}
>   {none}
>
> No code examples required.
>
> \funcdiff{ast\_aji\_send}
>   {/include/asterisk/jabber.h}
>   {int ast\_aji\_send(struct aji\_client *client, char *address, %
>     char *message);}
>   {int ast\_aji\_send\_chat(struct aji\_client *client, char *address, %
>     char *message);}
>   {function renamed for clarity}
>   {none}
>
> Note: a new ast\_aji\_send function is in 1.6.0
>
> \oldexheader
> \begin{verbatim}
> tatic int manager\_jabber\_send( struct mansession *s, struct message *m ) 
> { 
>     struct aji\_client *client = NULL; 
>     char *id = astman\_get\_header(m,"ActionID"); 
>     char *jabber = astman\_get\_header(m,"Jabber"); 
>     char *screenname = astman\_get\_header(m,"ScreenName"); 
>     char *message = astman\_get\_header(m,"Message"); 
>     ...
>     if (strchr(screenname, '@') && message){ 
> -->     ast\_aji\_send(client, screenname, message); 
>         if (!ast\_strlen\_zero(id)) 
>             astman\_append(s, "ActionID: %s\r\n",id); 
>         astman\_append(s, "Response: Success\r\n"); 
>         return 0; 
>     } 
>     ...
> \end{verbatim}
>
> \newexheader
> Exactly the same as above, except using the new function name:
>
> \begin{verbatim}
> -->     ast\_aji\_send\_chat(client, screenname, message); 
> \end{verbatim}
>
>
> \end{document}
>
>
>
> So the problems we see:
>
> * '_' (and '#'?) needs escaping
> * Explicit verbatim envirnment around the examples. I can't think of a
>   nice way to wrap this with macros.
>
>   

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.digium.com/pipermail/asterisk-dev/attachments/20090302/4be6b7ba/attachment.htm