Re: Setting HTML tags in C-style comments.

[James Henstridge <james daa com au>]

On 29/08/03 19:59, Rich Burridge wrote:

> Hi all,
>
> I've defined a C-style API for GNOME for doing collaboration called Share. 
>
> See:
>
> http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&dir=Share
>
> I've written the comments in the .c source files to use gtk-doc for 
> the documentation. That seems to be working fine except that I want 
> it to recognize (and correctly handle) various HTML tags sprinkled 
> throughout the comments in the code. See line 55-63 in:
>
> http://cvs.gnome.org/bonsai/cvsblame.cgi?file=Share%2Fshare/share_byte_array.c&r
> ev=&root=/cvs/gnome
>
> for example.
>
> Note that it only has to understand:
>
> <UL></UL>
> <LI></LI>
> <P></P>
>
> Now I have:
>
> MKDB_OPTIONS=--sgml-mode --output-format=xml
>
> in my .../docs/reference/Makefile.am
>
> and that prevents the &lt substitution (etc), but at HTML generation 
> time I get a load of lines like:
>
> ...
> Writing Share-ShareSessionListener.html for 
> refentry(Share-ShareSessionListener)No template matches UL.
> No template matches LI.
> No template matches LI.
> No template matches LI.
> No template matches LI.
> No template matches LI.
> No template matches LI.
> No template matches LI.
> Writing Share-ShareSessionManager.html for refentry(Share-ShareSessionManager)
> No template matches UL.
> No template matches LI.
> ...
>
> and it generates HTML files which don't do the right thing (see attached
> file).
>
> Now I guess I have to add a template for this somewhere, and maybe adjust 
> a couple of files, but I'm not sure where.
>  
gtk-doc uses DocBook (XML or SGML) as the intermediate format.  If you 
want to have more structure in your documentation, you will need to mark 
up the docs using Docbook tags.  In order for gtk-doc to recognise the 
Docbook tags, you need to pass the --sgml-mode option, which it seems 
you are already doing.

The markup for bulleted lists is something like:
   <itemizedlist>
     <listitem>
       <para>item 1</para>
     </listitem>
     <listitem>
       <para>item 2</para>
     </listitem>
   </itemizedlist>

James.

--
Email: james daa com au
WWW:   http://www.daa.com.au/~james/