From ffcf37402aafb277ddd120192a4ef3f72991fd23 Mon Sep 17 00:00:00 2001
From: Stefan Kost <ensonic@users.sf.net>
Date: Mon, 21 Jun 2010 22:50:26 +0300
Subject: [PATCH] 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
-- 
2.11.4.GIT