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

[BJ Weschke]

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.
http://www.btwtech.com/