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

[Brandon Kruse]

>----- Original Message -----
>From: "Tzafrir Cohen" <tzafrir.cohen at xorcom.com>
>To: asterisk-dev at lists.digium.com
>Sent: Thursday, July 10, 2008 7:23:08 AM GMT -06:00 US/Canada Central
>Subject: Re: [asterisk-dev] XML documentation of apps/functions/the_rest_of_the_world
>
>Hi
>
>Looking at the documentation in
>http://svn.digium.com/svn/asterisk/team/group/appdocsxml/apps/app_dial.c
>
>The description is something in the lines of:
>
>
>    <description>
>          dflkjsd g;ldsfkjg ;dsflgkj d;glk jdsf;glkj sdf;glkj d;fgl
>	  kjsd;gl jsd;gljk df;lgj d;fglkj d;glk jdsf;glkj dsf;gl jd;g
>	  jd;gljdf ;lkdfjg ;lsfdj g
>
>	  d;flgj ;lsdfkjfg ;dflgj d;lgj ;dflgj;lfdjg ;dflkgj ;dlkgj
>	  ;dlgj ;dflj d;flgj d;gl d;flg j;dflgj df;gljdf;lgjdf ;ldjg
>	  ;dlfjg 
>   </description>
> 
>What exactly breaks a paragraph?
>

No paragraph breaking, but rather it uses the newlines of a normal
unix document (\n) or (\r\n)

>There seem to be some '\n' here and there.
>
>
>Next thing: translation. A completely separate tree for a different
>language means replication of data. Consider the work needed to be done
>to add an option, or to add an optional parameter. If we also want to
>rely on the same text for validaation, tis redundancy is not a good
>thing.
>

Who said ANYTHING about a completely separate tree?

That is why we have the "owner" of the translation (in a perfect world)

How do you think others deal with this problem?

There is NO clear cookie cutter way to do it. Projects like mantis have
the best translations possible, and when new things come out, they are simply
undocumented. However, if I did not read any english, and could only read
spanish, not having a documented option would be ideal, and allow me to
use the pbx.

We have to weigh out our options in terms of what is more productive and usefull.

>Consider, for instance, the .desktop files. Here's an example one
>(/usr/share/applications/eog.desktop)
>
>[Desktop Entry]
>Name=Image Viewer
>Name[af]=Beeldbekyker
>Name[am]=የምስል ተመልካች
>Name[ar]=عارض الصّور
>Name[as]=ছবি প্ৰদৰ্শক
>Name[az]=Rəsm Nümayişcisi
>Name[be]=Глядач малюнкаў
>Name[be at latin]=Ahladalnik vyjavaŭ
>
>  [snip, I guess you get the point]
>
>Comment=Browse and rotate images
>Comment[ar]=تصفح و أدر الصور
>Comment[as]=চৰক এবং
>Comment[be]=Праглядай і паварочвай малюнкі
>Comment[be at latin]=Ahladaj i pavaročvaj vyjavy
>Comment[bg]=Преглед и завъртане на изображения
>Comment[bn_IN]=ছবি ব্রাউজ করুন ও ঘুরিয়ে নিন
>Comment[ca]=Navegueu per imatges i gireu-les
>Comment[cs]=Procházení a otáčení obrázků
>Comment[da]=Gennemse og rotere billeder
>Comment[de]=Bilder betrachten und rotieren
>  
>  [ snip again. But wait... ]
>
>TryExec=eog
>Exec=eog %U
>Icon=eog
>StartupNotify=true
>Terminal=false
>Type=Application
>Categories=GNOME;GTK;Graphics;RasterGraphics;Viewer;
>X-GNOME-Bugzilla-Bugzilla=GNOME
>X-GNOME-Bugzilla-Product=EOG
>X-GNOME-Bugzilla-Component=general
>X-GNOME-Bugzilla-Version=2.22.2
>X-GNOME-DocPath=eog/eog.xml
>MimeType=image/bmp;image/gif;image/jpeg;image/jpg;image/pjpeg;image/png;image/tiff;image/x-bmp;image/x-gray;image/x-icb;image/x-ico;image/x-png;image/x-portable-anymap;image/x-portable-bitmap;image/x-portable-graymap;image/x-portable-pixmap;image/x-xbitmap;image/x-xpixmap;image/x-pcx;image/svg+xml;image/svg+xml-compressed;image/vnd.wap.wbmp;
>
>So there are things you simply don't need to translate. But in this
>example, the documentation is mixed well with the other meta-data, and
>thus we have to translate everything.
>
>If we want good validation, we need to keep the data compact and make
>them easy to be merged at module load-time (or application registration
>time?)
>
>
>Suppose the application Foo in our documentation takes no parameters.
>Now I unload the standard module and load a module that includes Foo()
>that has two parameters. When and how will the application metadata in
>Astrisk be invalidated?
>

So you are saying you have an app, for example, that registers "Dial", then
you unload app_dial, and load app_thisisstupid.so, which registers application
Dial.

First of all, I do not see how that would EVER happen, and why you would want
to have such confusion. Second of all, the app_thisisstupid.so does NOT use
ast_register_application_xml, it will just use app_register_application, like
a normal app.

If you really wanted to do this (which I, will not), you could have one app be
part of 'core' and one of them be a 'third party app'

I would hope you would want to have these conflicts figured out before hand.

>-- 
>               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
>
>_______________________________________________
>--Bandwidth and Colocation Provided by http://www.api-digital.com--
>
>AstriCon 2008 - September 22 - 25 Phoenix, Arizona
>Register Now: http://www.astricon.net
>
>asterisk-dev mailing list
>To UNSUBSCRIBE or update options visit:
>   http://lists.digium.com/mailman/listinfo/asterisk-dev
>

-Brandon