[gtk-list] Re: Experimental GTK DocBook documentation

[Felix Bellaby <felix pooh u-net com>]

Carlos A M dos Santos writes:
 > I vote for a reference into the source code to an external file base
 > name, like this:
 > 
 > /*
 > **	<gtkbook>
 > **	  <function name="gtk_blah_blah_blah">
 > **	    <parameters>
 > **	      <parameter name="blih" type="bloh">
 > **	      :
 > **	    </parameters>
 > **	    <description>
 > **		This function zag zeg zig zog zug
 > **	    </description>
 > **	    <doc file="gtk_blah_blah_blah">
 > **	  </function>
 > **	</gtkbook>
 > */

This translation problem makes me think of gettext...

The source comments are short pieces of text in the C locale and we 
want to convert them to translations in other locales (including en) 
that are rather more extensive in their content.

gettext is not designed to handle this specific task but you could use 
it something like this:

1) the source could have simple comments entered like this:

source.h
#define COMMENT(x) #define _COMMENT _N(x)

source.c:
...
COMMENT("This function zag zeg zig zog zug")
...

2) xgettext could be used to generate a PO file for each locale from
   this source which listed all the COMMENT(..) entries opposite a place 
   to enter an extended translation. E.g.

fr.po:
#: source.c:72 
msgid "This function zag zeg zig zog zug"
msgstr "Le function zag zeg zig zog zug zig zog zug"

3) Now run 

grep COMMENT *.c > temp.c

   and compile the following (linking in gettext)

doc.c:
#define COMMENT(x) printf(_(x));
#include <stdio.h>

int main(int, char**) {
#include temp.c
}

5) Choose a locale and run doc to print out the translated comments.

I am sure a better job could be done of implementing this with a 
bit more thought but you get the idea. Any DocBook like tags could be
added by having one COMMENT-like macro for  each of the different
types of COMMENT lines.

Felix


PS: Using xgettext on this would not work (AFAIK)

/*
..
 * _N(This function zag zeg zig zog zug)
..
 */