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

[Tzafrir Cohen]

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?

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.

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?

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