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

BJ Weschke bweschke at gmail.com
Mon Jul 14 20:05:07 CDT 2008

Tilghman Lesher wrote:
> On Monday 14 July 2008 16:51:29 Michiel van Baak wrote:
>> 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.
> I don't think there's any need to keep the documentation directly within the
> source file itself.  In fact, I think that's where having a separate XML file
> would be beneficial, in terms of not requiring the documenteurs to edit
> source files in order to update documentation.

 +1 to this concept. I think we should keep it separated when possible.

Bird's The Word Technologies, Inc.

More information about the asterisk-dev mailing list