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

[Michiel van Baak]

On 09:23, Wed 09 Jul 08, Caio Begotti wrote:
> On Tue, 8 Jul 2008 13:28:23 -0500 (CDT)
> Brandon Kruse <bkruse at digium.com> wrote:
> 
> > >Instead of a node for each language what about merging different
> > >XML files for each one of them? Too hackish? Let's say there are 7
> > >amazing Asterisk local groups out there looking forward to send
> > >their massive translations :)
> > 
> > That wouldn't be a problem in the sense that it's XML, it is still
> > parsed by the language= attribute, after the nodes are parsed into
> > a group by application/function name. We are still defining the
> > spec/schema, but I think that a few more languages would not be bad
> > at all.
> 
> I understand but my concern was kind of different, don't get me
> wrong as a picky person, I really appreciate the effort on this :-)
> 
> From my dirty and ridiculos grep in the trunk tree I'd say there are
> 1200 lines of modules descriptions and their synopsis. Without any
> XML tag or indenting that would potentially increase it even more.
> 
> Right now there are pratically 15 languages supported in say.c, but
> let's assume only 5 of them have active doc guys doing some
> localization on their own. This unique XML file would end up being
> pretty huge if I'm not completely wrong. That's why I suggested the
> multiple XML files approach for multilanguage support, though I see
> it can be considered a minor.
> 
> Another issue that would eventually appear is The Charset Hell.
> 
> These are not big deals actually, but I guess they must be
> taken in account if the idea has multiple purposes :-)

We decided to go this route:
Put the english documentation in the source.
Generate core-en.xml on build time and load strings from their on module
load.
Translators can take this file, and name it core-$language.xml
if you specify $language in /etc/asterisk/asterisk.conf by
documentation_language asterisk will use that file. (and thus that
language)

We will also support loading additional files, so non-in-tree modules
can have their own xml file(s)
-- 

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?"