Re: [xmlroff] xmlroff release is delayed

[Tony G. <Ton...@Su...>]

Stefan Seefeld <se...@sy...> writes:
> Tony Graham wrote:
>>>Speaking of which, do you have a tool to generate documentation from your
>>>source code ? Synopsis has a new C parser and I'm looking for a victim... :-)
>> gtk-doc.
>> Can Synopsis parse gtk-doc comments?
>
> yes, you can teach it to parse comments as you want, by means of python
> modules.

I'm sure someone could.  Once done, it would of course be usable by
any GTK+/GNOME-like project.

>> Can Synopsis included "static" documentation and annotations to the
>> generated documentation in the way that gtk-doc can?
>
> I'm not sure what you mean in detail, but it is certainly possible
> to either include links to external docs, or even mix in existing
> documents into a single generated document.

I hope that you have looked at the generated documentation at some
point...

The sections under "Things to know" are "static" documentation
generated from DocBook documents in the 'docs' directory.

The files in docs/tmpl are initially generated by gtk-doc, but it's
possible to add snippets of DocBook markup to them, and the snippets
will be included in the appropriate place in the generated HTML.

...
>> If you can modify configure.in to enable Synopsis documentation
>> generation (with no ill-effect if Synopsis is not present) just as
>> --enable-gtk-doc enables gtk-doc documentation, then you can check it
>> in.
>> Synopsis would have to be an option alongside gtk-doc, and for the
>> moment at least, the xmlroff distributions would still ship with
>> gtk-doc documentation.
>
> I'll have a look. If gtk-doc is already doing a fine job for what
> you want it to do there is no reason to change / add anything.

Synopsis appears to have some interesting features, and I'd be more
inclined to use it if all it took was a make target.

Regards,


Tony.