[asterisk-dev] XML documentation of apps/functions/the_rest_of_the_world

[Michiel van Baak]

On 16:10, Mon 14 Jul 08, Tilghman Lesher wrote:
> On Monday 14 July 2008 15:19:02 Brandon Kruse wrote:
> > >----- Original Message -----
> > >From: "Russell Bryant" <russell at digium.com>
> > >To: "Asterisk Developers Mailing List" <asterisk-dev at lists.digium.com>
> > >Sent: Sunday, July 13, 2008 2:02:21 PM GMT -06:00 US/Canada Central
> > >Subject: Re: [asterisk-dev] XML documentation of
> > > apps/functions/the_rest_of_the_world
> > >
> > >On Jul 12, 2008, at 7:43 PM, Michiel van Baak wrote:
> > >> Me myself is not really happy with this, but I can understand the
> > >> reason
> > >> why this would be needed.
> > >> I think this takes some of the more flexible and cool stuff we can do,
> > >> but on the other hand the trouble we could get from it may be worse.
> > >
> > >Well hopefully we can come up with a solution where don't lose the
> > >flexibility you guys have been working toward, while also avoiding the
> > >complexities of having the documentation, including the argument and
> > >option meta data, not strictly tied to the module it pertains to.
> > >
> > >> I'll talk it over with bkruse to see what we can do here.
> > >>
> > >> As soon as we come up with something we will post it here for review.
> > >
> > >Sounds good.  Of course, if anyone else has any proposals on the
> > >mechanics of doing this, please propose them here.
> >
> > Ok, very good suggestions. I did not mean to seem to get angry with
> > tzafrir, he is my buddy, I am just on vacation, and it's suckin :P
> >
> > As Kevin mentioned, it would be great to be able to access the
> > documentation from the actual compiled modules, so that we do not have a
> > file.xml anywhere.
> >
> > I think it IS great, however, to have the ABILITY to get the documentation
> > OUT of the module, and into a file in a parseable format.
> >
> > Accomplishing this means two things.
> >
> > 1) We do what Kevin mentioned and we access the documentation from the
> > actual module.
> >
> > 2) Be able to export that documentation on build-time OR runtime (maybe?)
> > to an external file with version information, so nothing gets confused. If
> > we are going to do all this, let us make sure we do not make the same
> > mistake many do, and try to get the version information right the first
> > time, which will be a HUGE benefit to us.
> 
> I think you misunderstood the concept.  Initially, in the source, the
> documentation is held in some format.  It may be XML, it might be
> something else.  At compile/link time, the documentation (for all languages)
> will be loaded into the object file format, either embedded as strings within
> the data section, or embedded into its own section within the object file.
> For documentation that is queried during the Asterisk runtime, it will be
> accessed directly from this module.  In other words, when it comes to
> "core show application Foo", very little changes from the current method.
> There is no XML to be parsed; the text is simply displayed.  The only big
> change will be that the documentation embedded into the module may be
> in multiple languages.
> 
> The documentation still exists in the source directory in XML format and may
> be exported to other formats (Postscript, PDF, Docbook, etc.).  So all that
> we'd really be changing at this stage is where the documentation is stored
> within the source; instead of the documentation stored as a string within a
> C source file, the documentation will be stored within an external XML file.
> Only at compile/link time will the documentation be added directly to the
> module.
> 
> This makes it easy to export the documentation to other formats, while at
> the same time, not dramatically increasing the amount of processing the
> Asterisk binary needs to do in order to display documentation.  I think that
> provides a nice balance between being able to do more things with the
> embedded documentation (and making the documentation easier to update
> and internationalize) and ensuring that there is no confusion or extra
> processing required by the Asterisk binary to display its own documentation.

Like this post ?
http://lists.digium.com/pipermail/asterisk-dev/2008-July/033948.html

bkruse and me had some talk about it and this is the gist of it.
-- 

Michiel van Baak
michiel at vanbaak.eu
http://michiel.vanbaak.eu
GnuPG key: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x71C946BD

"Why is it drug addicts and computer aficionados are both called users?"