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

[Tzafrir Cohen]

On Mon, Jul 14, 2008 at 05:30:21PM -0500, 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.

Alternatively: embed original English documentation. Translation will be
done using gettext?

After a chat at #asterisk-dev it seems not everybody likes this idea.

Pros: we don't need to invent our own translation infrastructure. And
can easily translate module documentation after build time in a robust
way. It allows good separation between text and metadata.

Cons: [ space is reserved for replies ]

-- 
               Tzafrir Cohen
icq#16849755              jabber:tzafrir.cohen at xorcom.com
+972-50-7952406           mailto:tzafrir.cohen at xorcom.com
http://www.xorcom.com  iax:guest at local.xorcom.com/tzafrir