tmpl/ to xml/ without DOCTYPE front matter

[Philip Kovacs]

I notice that when I edit a tmpl/ template file and rebuild, the
corresponding
xml/ file gets the DOCTYPE front matter from the PROJECT-docs.sgml file,
which unfortunately includes all the ENTITY's that I added to that
-docs.sgml
file, of the form:

<!ENTITY Something SYSTEM "xml/project-something.xml">

The .xml file in xml/ do not compile due to those echoed entities, since the
the current directory has shifted down one level, i.e. into xml/.

I find that I have to manually rip out everything before <refentry id="">
in the xml/ files after editing the templates.

It seems as those I have to distrtibute both the tmpl/ and the edited xml/
files as well in order for people to build proper docs.  I notice the gtk+
tarballs do just that, i.e. distribute xml/ files with the DOCBOOK/ENTITY
front matter all (manually?) ripped out.

No auto way to do this?

Phil
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

Hi Philip,

I also once struggled with a similar issue. Anyway there is no need to
edit the tmpl files. You can comment inside the sources and hopefully,
one day, there won't be any tmpl files anymore.

Stefan

Philip Kovacs wrote:

> I notice that when I edit a tmpl/ template file and rebuild, the
> corresponding
> xml/ file gets the DOCTYPE front matter from the PROJECT-docs.sgml file,
> which unfortunately includes all the ENTITY's that I added to that
> -docs.sgml
> file, of the form:
>
> <!ENTITY Something SYSTEM "xml/project-something.xml">
>
> The .xml file in xml/ do not compile due to those echoed entities, since the
> the current directory has shifted down one level, i.e. into xml/.
>
> I find that I have to manually rip out everything before <refentry id="">
> in the xml/ files after editing the templates.
>
> It seems as those I have to distrtibute both the tmpl/ and the edited xml/
> files as well in order for people to build proper docs.  I notice the gtk+
> tarballs do just that, i.e. distribute xml/ files with the DOCBOOK/ENTITY
> front matter all (manually?) ripped out.
>
> No auto way to do this?
>
> Phil
> _______________________________________________
> gtk-doc-list mailing list
> gtk-doc-list@...
> http://mail.gnome.org/mailman/listinfo/gtk-doc-list
>  

_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Philip Kovacs]

Hi.

How can I indicate in the source code the various sections, i.e.
short/long description,
"See also", etc.   That's the only thing I was actually editing the
templates for.

Thanks.

Phil

Stefan Kost wrote:

> Hi Philip,
>
> I also once struggled with a similar issue. Anyway there is no need to
> edit the tmpl files. You can comment inside the sources and hopefully,
> one day, there won't be any tmpl files anymore.
>
> Stefan
>
> Philip Kovacs wrote:
>  
>> I notice that when I edit a tmpl/ template file and rebuild, the
>> corresponding
>> xml/ file gets the DOCTYPE front matter from the PROJECT-docs.sgml file,
>> which unfortunately includes all the ENTITY's that I added to that
>> -docs.sgml
>> file, of the form:
>>
>> <!ENTITY Something SYSTEM "xml/project-something.xml">
>>
>> The .xml file in xml/ do not compile due to those echoed entities, since the
>> the current directory has shifted down one level, i.e. into xml/.
>>
>> I find that I have to manually rip out everything before <refentry id="">
>> in the xml/ files after editing the templates.
>>
>> It seems as those I have to distrtibute both the tmpl/ and the edited xml/
>> files as well in order for people to build proper docs.  I notice the gtk+
>> tarballs do just that, i.e. distribute xml/ files with the DOCBOOK/ENTITY
>> front matter all (manually?) ripped out.
>>
>> No auto way to do this?
>>
>> Phil
>> _______________________________________________
>> gtk-doc-list mailing list
>> gtk-doc-list@...
>> http://mail.gnome.org/mailman/listinfo/gtk-doc-list
>>  
>>    
>
>
>  

_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[David Nečas (Yeti)-2]

On Tue, Sep 26, 2006 at 05:20:47PM -0400, Philip Kovacs wrote:
> How can I indicate in the source code the various sections, i.e.
> short/long description,
> "See also", etc.   That's the only thing I was actually editing the
> templates for.

Like this:

/**
 * SECTION:gwydataview
 * @title: GwyDataView
 * @short_description: Data field displaying area
 * @see_also: #GwyDataViewLayer...
 *
 * #GwyDataView is a basic two-dimensional data display widget...
 *
 * This is the long description...
 **/

The following section tags currently exist: SECTION (the
section identifier), @title, @short_description, @see_also
and @stability.

Yeti


--
Anonyms eat their boogers.
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Philip Kovacs]

>/**
> * SECTION:gwydataview
> * @title: GwyDataView
> * @short_description: Data field displaying area
> * @see_also: #GwyDataViewLayer...
> *
> * #GwyDataView is a basic two-dimensional data display widget...
> *
> * This is the long description...
> **/
>
>The following section tags currently exist: SECTION (the
>section identifier), @title, @short_description, @see_also
>and @stability.

Great.  The only thing I need to change in my descriptions
is my use of c-style comments (/* */) in my code examples.  
Looks like I need to create xml entity references for these
in my -docs.sgml because the compiler doesn't like nested
comments.

Phil

_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[David Nečas (Yeti)-2]

On Wed, Sep 27, 2006 at 08:55:33PM -0400, Philip Kovacs wrote:
>
> Great.  The only thing I need to change in my descriptions
> is my use of c-style comments (/* */) in my code examples.  
> Looks like I need to create xml entity references for these
> in my -docs.sgml because the compiler doesn't like nested
> comments.

Well, I'd rather calls entities abused than used for this
purpose, XInclude does directly what one needs...

Anyway, C style comment are possible.  A couple of basic
embedded code samples tricks:

/**
 * ...
 * <informalexample><programlisting>
 * GtkWidget *w;
 * <!-- Make an empty line avoiding autoparagraphization -->
 * w = gtk_tree_view_new<!-- -->();  <!-- Prevent linkification -->
 * /<!-- -->* Insert a C comment to the example *<!-- -->/
 * ...
 * </programlisting></informalexample>
 **/

And thanks to the fact DocBook processing is typically set
not to preserve comments, the resulting HTML does not
contain any of this rubbish, it only clutters the source
code.

Yeti


--
Anonyms eat their boogers.
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Damon Chaplin]

On Thu, 2006-09-28 at 07:22 +0200, David Nečas (Yeti) wrote:

> On Wed, Sep 27, 2006 at 08:55:33PM -0400, Philip Kovacs wrote:
> >
> > Great.  The only thing I need to change in my descriptions
> > is my use of c-style comments (/* */) in my code examples.  
> > Looks like I need to create xml entity references for these
> > in my -docs.sgml because the compiler doesn't like nested
> > comments.
>
> Well, I'd rather calls entities abused than used for this
> purpose, XInclude does directly what one needs...
>
> Anyway, C style comment are possible.  A couple of basic
> embedded code samples tricks:
>
> /**
>  * ...
>  * <informalexample><programlisting>
>  * GtkWidget *w;
>  * <!-- Make an empty line avoiding autoparagraphization -->

You can just use an extra space here for an empty line, e.g. " *  ".

>  * w = gtk_tree_view_new<!-- -->();  <!-- Prevent linkification -->
>  * /<!-- -->* Insert a C comment to the example *<!-- -->/

I just use * here.

>  * ...
>  * </programlisting></informalexample>
>  **/
>
> And thanks to the fact DocBook processing is typically set
> not to preserve comments, the resulting HTML does not
> contain any of this rubbish, it only clutters the source
> code.

I created a little script to convert C code to make it ready to go into
gtk-doc comments. I've attached it here.

Maybe I should add it to gtk-doc.

Damon



_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[David Nečas (Yeti)-2]

On Thu, Sep 28, 2006 at 09:21:42AM +0100, Damon Chaplin wrote:
> >  * <!-- Make an empty line avoiding autoparagraphization -->
>
> You can just use an extra space here for an empty line, e.g. " *  ".

You can, but semantic trailing spaces does not seem like
a good idea to me, it's very easy to lose such a space.
Especially when someone considers trailing spaces a coding
style error.  The comment is uglier but persistent.

Yeti


--
Anonyms eat their boogers.
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Philip Kovacs]

>
> /**
>  * ...
>  * <informalexample><programlisting>
>  * GtkWidget *w;
>  * <!-- Make an empty line avoiding autoparagraphization -->
>  * w = gtk_tree_view_new<!-- -->();  <!-- Prevent linkification -->
>  * /<!-- -->* Insert a C comment to the example *<!-- -->/
>  * ...
>  * </programlisting></informalexample>
>  **/

Terrific!   Now I have no need to edit templates or create entities to
deal with the
surrounding comment blocks.

Phil
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list