[gtk-doc] planning: write down ideas and add FIXME: comments

[Stefan Kost <stefkost src gnome org>]

commit ffcf37402aafb277ddd120192a4ef3f72991fd23
Author: Stefan Kost <ensonic users sf net>
Date:   Mon Jun 21 22:50:26 2010 +0300

    planning: write down ideas and add FIXME: comments

 TODO              |   12 +++++++-----
 gtkdoc-fixxref.in |    3 +++
 gtkdoc-mkdb.in    |    1 +
 3 files changed, 11 insertions(+), 5 deletions(-)
---
diff --git a/TODO b/TODO
index 6cf0059..4db27ff 100644
--- a/TODO
+++ b/TODO
@@ -196,9 +196,11 @@ We need parametric, user definable macros.
   - and replace the macro with it
 The changes could be made in gtkdoc-mkdb::ExpandAbbreviations()
 === example macros ===
-|highlight(c)[...]| - highlight source code for a specific language
-|dot(abc.svg)[...]| - format dot graph and include result as mediaobject
-|ditta(abc.svg)[...]| - parse ascii art and include result as mediaobject
+|highlight(c)[...]| - highlight source code for a specific language (c)
+  - what will this output? preformatted html to be xincluded?
+|dot(svg)[...]| - format dot graph and include result as mediaobject (in svg format)
+|ditta(svg)[...]| - parse ascii art and include result as mediaobject (in svg format)
+  - we need to generate a filename for the image or use anoter parameter
 
 === where to define macros ===
 * system wide and with the package, <prefix>/share/gtk-doc/macros, $(srcdir)
@@ -243,7 +245,7 @@ http://www.tjkdesign.com/articles/how_to_style_a_code_listing.asp
 === process docbook ===
 if we highlight to docbook, we just get emphasis (bold)
 === process html ===
-if we hightlight to html we get colors, we need to check what tags we should process though:
+if we highlight to html we get colors, we need to check what tags we should process though:
 <pre class="programlisting"> is used for all code boxes.
 <div class="informalexample"><pre class="programlisting"> is used for examples.
 problems:
@@ -259,7 +261,7 @@ problems:
   emacs: http://www.delorie.com/gnu/docs/emacs/emacs_486.html
 * allow <!-- language="C" --> comments after |[
 * we need to catch those when processing the docbook and expanding the |[
-
+* require new macro syntax
 
 
 = syntax =
diff --git a/gtkdoc-fixxref.in b/gtkdoc-fixxref.in
index 786770a..33a31b8 100755
--- a/gtkdoc-fixxref.in
+++ b/gtkdoc-fixxref.in
@@ -291,6 +291,9 @@ sub FixHTMLFile {
     close (HTMLFILE);
     
     if ("@HIGHLIGHT@" ne "") {
+        # FIXME: ideally we'd pass a clue about the example language to the highligher
+        # unfortunately the "language" attribute is not appearing in the html output
+        # we could patch the customization to have <code class="xxx"> inside of <pre>
         if ("@HIGHLIGHT@" =~ m%/vim$%) {
             $entire_file =~ s%<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>%&HighlightSourceVim($1,$2);%gse;
         }
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index 6ec3474..c761c85 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -2652,6 +2652,7 @@ sub ExpandAbbreviations {
   my ($symbol, $text) = @_;
 
   # Convert "|[" and "]|" into the start and end of program listing examples.
+  # FIXME: we like to have a way to specify parameters e.g. language="c"
   $text =~ s%\|\[%<informalexample><programlisting>%g;
   $text =~ s%\]\|%</programlisting></informalexample>%g;
   # TODO: check for a xml comment after |[ and pick the language attribute from