Re: Allowing docbook markup in inline docs (2)

["Matthias Clasen" <matthiasc poet de>]

----- Original Message -----
From: "Havoc Pennington" <hp redhat com>
To: "Matthias Clasen" <matthiasc poet de>
Cc: <gtk-devel-list gnome org>; <gtk-doc-list gnome org>
Sent: Thursday, September 27, 2001 5:53 PM
Subject: Re: Allowing docbook markup in inline docs (2)


>
> "Matthias Clasen" <matthiasc poet de> writes:
> > Even with this patch in place, I would still like to use explicit
docbook
> > markup for emphasis, filenames, envvars, etc
> > in inline comments.
>
> I would also, I think it's essential to getting decent docs. There are
> a bunch of currently-slightly-wrong doc entries that suffer from this
> lack.

Yes, I noticed that.

> It's a bit unclear how it interacts with the automarkup; what did your
> patch do here? e.g. if I have:
>
>  foo bar foo() bar #blah blah blah
>
>  blah blah blah
>
> Then I end up with something like:
>
>  <para>foo bar <link>foo</link> bar <link>blah</link> blah blah</para>
>
>  <para>blah blah blah</para>
>
> In SGML mode do we still do all that, and you just have to know to
> avoid tricking gtk-doc into creating invalid SGML?

Yes, we still need the abbreviations unless you expect the doc authors
to be able to reliably reproduce the name mangling done by the gtkdoc
scripts
to derive SGML IDs for cross-references.

As I tried to explain, the only real problem case for the interaction of
abbreviations and explicit markup is functions. My patch to make
abbreviations
create proper docbook markup for non-crossreferencable items will currently
create duplicate markup for explicitly marked up functions like
<function>strlen()</function>.
(note that this is not a problem for types, since <type>#int</type> is just
a markup
error).

We can probably get around this problem by making the expansion of
abbreviations
context-sensitive:

strlen()</function>    -->    <link
linkend="strlen">strlen</link>()</function>

strlen()                     -->    <function><link
linkend="strlen">strlen</link>()</function>,

ie only surround the link with <function> tags if there isn't already a
function endtag following.
I'll change my patch to do that.

>
> Something other than /*** might be good, maybe /** SGML
>

Well, I was looking for something unintrusive, since I would expect the
"SGML mode" to be
the default for new entries. Your proposal has one advantage over mine:
older versions of
gtk-doc will still recognize the SGML mode doc comments and try to handle
them as good as
they can (currently '/** ' triggers the start of a doc comment, thus '/***'
comments will be
ignored by older versions of gtk-doc).

But I'm open for other proposals.

> BTW, there is a gtk-doc-list gnome org mailing list, which is where
> all this probably belongs.
>

Ok, lets move over here...


> > PS I would really appreciate if someone with the necessary privileges
could
> > create a gtk-doc bugzilla category, so
> > that I can stick my patches there.
>
> Done, hopefully no one will mind.

Thanks.

Matthias