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

[Tilghman Lesher]

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.

-- 
Tilghman