GNOME Bugzilla – Bug 467488
GTK+ man pages request
Last modified: 2010-06-13 12:05:56 UTC
Would be nice if GTK+ Doc could generate man pages too. All Vim users (I'm too) could apprecciate it really much.
It could do that in theory. I have opened a ticket already for pdf output. It basically means investigate the other possible xsl output chains. How should it be like. One page per class (GtkWidget). It would be great it you could help wth getting the concept clear and investigating how to convert a docbook xml into man-pages. Feel free to look for useful info and post links here.
(In reply to comment #1) > It could do that in theory. I have opened a ticket already for pdf output. It > basically means investigate the other possible xsl output chains. > > How should it be like. One page per class (GtkWidget). > > It would be great it you could help wth getting the concept clear and > investigating how to convert a docbook xml into man-pages. Feel free to look > for useful info and post links here. > Thanks for you fast reply. I think one page per class is a good solution since maybe can make life easier to you. I did a check in reference/ under the gtk+ source tree and I saw that sgml files are already there, so maybe you can manage to let them to compile. I tried docbook2man but it gave me some prolog errors which aren't my cup of tea. I think following the same structure of the actual html documentation is the best idea. From the Vim side, this doesn't change a lot since you get the cursor over a page, press K and you get the referenced doc. Temporarly I config Vim to use devhelp instead of man pages and works good but with man pages it would be much better. Best Regards S.
Created attachment 93845 [details] alternative View gtkdoc documentation of a symbol using a HTML browser of your choice. Easily integrable to vim, ideally probably with keywordprg set to something like #!/bin/sh gtkdoc-view "$@" || man "$@" Supports all kinds of stuff present in the documentation: fuctions: gtk_main() macros: FALSE structs and objects: GtkTreeModel typedefs: gboolean individual enum values: GTK_ARROW_DOWN (hardly will be ever supported by man) signals: GtkWidget::hide properties: GtkCellRenderer:height I've been using something similar (though a bit more complex) for years in vim. Definitely do not count me in `all vim users' that would appreciate man pages.
I've tried mkdir man xsltproc --nonet --xinclude --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version "1.9" /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl ../tester-docs.sgml and it worked! docbook2man uses jade and requires sgml. Despite the name most of the projects use xml these days.
(In reply to comment #3) > Created an attachment (id=93845) [edit] > alternative This look really nice, expecially cause you can configure the browser.. links is really perfect and much better than devhelp. I used something more easy with devhelp since it allows to search a term with devhelp -s <SYMBOL>, so i did #!/bin/sh devhelp -s "$1" Thanks to you for your sharing! > View gtkdoc documentation of a symbol using a HTML browser of your choice. > Easily integrable to vim, ideally probably with keywordprg set to something > like > > #!/bin/sh > gtkdoc-view "$@" || man "$@" I set keywordprg=gtkdoc-view and it works good, I think Vim already pass the parameter.
(In reply to comment #4) > I've tried > > mkdir man > xsltproc --nonet --xinclude --stringparam gtkdoc.bookname tester --stringparam > gtkdoc.version "1.9" > /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl > ../tester-docs.sgml > > and it worked! Ah, very nice.. so I think It's just a matter to tune the Makefile to allow the generation of man pages. > docbook2man uses jade and requires sgml. Despite the name most of the projects > use xml these days. Gtk+ seems to include both since I can see a tmpl and xml dir. Maybe I get some errors cause I didn't configure docbook2man with the right stylesheet. I have sgml installed.
(In reply to comment #5) > > #!/bin/sh > > gtkdoc-view "$@" || man "$@" > > I set keywordprg=gtkdoc-view and it works good, I think Vim already pass the > parameter. Yes, vim passes the parameter, however, if you want to run gtkdoc-view *or* man depending on which of them can display the documentation of a symbol, some wrapper is necessary. Alternatively gtkdoc-view could just do `exec "man", @ARGV;' in the case of failure, although this would make it a bit too single-purpose for my taste.
(In reply to comment #4) > docbook2man uses jade and requires sgml. What you mean by `requires sgml'? tester is in the XML version of DocBook (like the documentation of most packages today).
(In reply to comment #7) > (In reply to comment #5) > > > #!/bin/sh > > > gtkdoc-view "$@" || man "$@" > > > > I set keywordprg=gtkdoc-view and it works good, I think Vim already pass the > > parameter. > > Yes, vim passes the parameter, however, if you want to run gtkdoc-view *or* man > depending on which of them can display the documentation of a symbol, some > wrapper is necessary. Alternatively gtkdoc-view could just do `exec "man", > @ARGV;' in the case of failure, although this would make it a bit too > single-purpose for my taste. > Yes, that's much better. Anyway exec in perl seems to have some problems with parameters. Seems to work only in this ugly way: my $viewer='/usr/bin/links2'; my $viewer_opt=' -g'; ... exec "$viewer$viewer_opt file://$file/$link"
(In reply to comment #9) > (In reply to comment #7) > > (In reply to comment #5) > > > > #!/bin/sh > > > > gtkdoc-view "$@" || man "$@" > > > > > > I set keywordprg=gtkdoc-view and it works good, I think Vim already pass the > > > parameter. > > > > Yes, vim passes the parameter, however, if you want to run gtkdoc-view *or* man > > depending on which of them can display the documentation of a symbol, some > > wrapper is necessary. Alternatively gtkdoc-view could just do `exec "man", > > @ARGV;' in the case of failure, although this would make it a bit too > > single-purpose for my taste. > > > > Yes, that's much better. > Anyway exec in perl seems to have some problems with parameters. > Seems to work only in this ugly way: > > my $viewer='/usr/bin/links2'; > my $viewer_opt=' -g'; > ... > exec "$viewer$viewer_opt file://$file/$link" > Ops..not really. my problem... exec $viewer, $viewer_opt, "file://$file/$link" works :)
Regarding comment #9, docbook2xxx script use jade to transform sgml documents. Most projects I know configure gtk-doc to use xml documents. Regardless of the mode, gtkdoc names the master-document xxx-docs.sgml (posted with a patch as bug #467773). I personally avoid jade (had some troubles with it). Anyway for the man/pdf generation we would need to support both like done for html.
oh and there is gtkdoc-mkman already. Its a bit unmaintained and not used by default.
If one actually documents tools in the library (like for glib : glib-genmarshal, glib-gettextize and glib-mkenums, it sould be useful to make manpages for those. Therefore we would need a way to configure which sub-pages to convert. Default is DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.sgml. If one writes then as separate files and xi:inlcudes them, one could just list those files. We could also locate them by finding files that contain a <manvolnum> tag.
GLib and GTK+ already do manpages for tools on their own. Might be worth checking out: man_MANS = \ glib-gettextize.1 \ gtester.1 \ gtester-report.1 if ENABLE_MAN %.1 : %.xml @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< endif BUILT_EXTRA_DIST = $(man_MANS)
commit 728b77acb9b3e06238d570b0d0cce296918132c2 Author: Stefan Kost <ensonic@users.sf.net> Date: Sun Jun 13 14:56:22 2010 +0300 help: tell how to build man-pages. Fixes #467488 Start a new section telling how to document other interfaces. Describe how to build man-pages. The section is based on how it is done it glib (comment #14). I think that all I can do for now on this topic.