This is offtopic from autotool technology, I did just observe that not many people have come to notice the benefits of omf/scrollkeeper for providing documentation to the local user of software.
* what is omf/scrollkeeper interesting bits can be found starting on http://scrollkeeper.sf.net "It manages documentation metadata (as specified by the Open Source Metadata Framework(OMF)) [link to osrt/omf given] and provides a simple API to allow help browsers to find, sort, and search the document catalog." .. [in browsers.html] "KDE's help browser has had ScrollKeeper support since the 2.x days." .. "Yelp will replace Nautilus as the GNOME help browser [in GNOME 2.x]". * installing documentation files The documentation files can be created and intalled traditionally, well here we do more deal with html (or xml) files than troff man pages. Actually, quite some projects have a doc/ subdirectory that carries project information along and they are installed somewhere in the system, in many cases into ${datadir}/doc/${PACKAGE} or perhaps just into ${datadir}/${PACKAGE}/html * the index/search problem there is no traditional directory for html/xml documentation, and a user has problems to (a) find the place and (b) search into it. The gnu .info files system has just that - one will install the files and make a call to `install-info` to register it in a central overview page, kinda `table of content`. An info-browser like `info` or `pinfo` can be used to read into it or even search for parts of interest. * the omf/scrollkeeper approach The omf has created a DTD for an xml format that can be used to register html documentation in the system - omf enabled browsers can read this TOC-like index file and present it to the user. The user can read it or search into it with the help provided by these browsers - both kde/gnome help browsers span across omf and troff pages. The tool of interest here is `scrollkeeper-update` - after having all the html files installed in a directory of your choice, the last step shall then be the installation of *.omf file(s) into ${datadir}/omf/${PACKAGE} followed by a call to scrollkeeper-update. No special arguments are needed when datadir/omf is present in the $OMF_DIR list or your scrollkeeper.conf * omf file creation The only trick is in creating a valid omf file. First of all, you need an omf key - because internally the omf registry does *not* work with the filepath of your *.omf file but only this numeric key. When multiple omf files with the same key are present only the newest is taken - that's great for renaming the omf file or installing multiple parallel versions of the same documents. A unique omf key can be created by `scrollkeeper-gen-seriesid`, and it should be run only once and the value be memorized in the doc/ makfile.in/makefile.am DOCSERIES = 1a894a10-1e10-11d7-83ae-a34c0931e5e5 The entries to be put into the xml-type omf file are sometimes not easy to grasp from the omf documentation, it took me some trial and error - my goal was to pick up most of the information from a rpm spec file. That actually a good idea - the "category" of the doc should match the value you've chosen for the rpm spec files "Group" entry since opensource categorization has already a common scheme across packaging systems (.rpm/.deb/slack etc), and the scrollkeeper tools/browsers have correct translations of these catagories at hand (better browsing experience!). Anyway, here is some real world example for you to pick up and modify according to the needs of your project: # ------------------------------------------------------------------- DOCSERIES= 775fb73e-1874-11d7-93e9-e18cd7ea3c2e FROMSPEC= zziplib.spec | head -1 | sed -e 's,<,\<,g' -e 's,>,\>,g' DATESPEC= `date +%Y-%m-%d` $(PACKAGE)-doc.omf : zziplib.spec Makefile echo '<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>' >$@ echo '<omf><resource><creator> Guido Draheim </creator>' >>$@ grep Packager $(FROMSPEC) | sed -e 's,Packager *: *, <maintainer>,' \ -e '/<maintainer>/s,$$,</maintainer>,' >>$@ grep Summary $(FROMSPEC) | sed -e 's,Summary *: *, <title>,' \ -e '/<title>/s,$$,</title>,' >>$@ echo ' <date>'$(DATESPEC)'</date>' >>$@ echo ' <version identifier="$(VERSION)" date="'$(DATESPEC)'"/>' >>$@ grep Group $(FROMSPEC) | sed -e 's,Group *: *, <subject category=",' \ -e 's,/,|,g' -e '/<subject/s,$$," />,' >>$@ echo ' <format mime="text/html"/>' >>$@ echo ' <identifier url="file:$(pkgdocdir)/index.html"/>' >>$@ echo ' <language code="C"/>' >>$@ echo ' <relation seriesid="$(DOCSERIES)"/>' >>$@ echo ' <rights type="GNU LGPL" holder="Guido Draheim"' >>$@ echo ' license="$(pkgdocdir)/COPYING.LIB"/>' >>$@ echo '</resource></omf>' >>$@ Note that documentation was installed to $(pkgdocdir) and has a starting point of index.html and carries also a copy of COPYING.LIB. The specfile "Group" has "Development/Libraries" which `yelp` shows as "Entwicklung"-> "Bibliotheken" in German. The doc files themselves are english and placed here as "<language code="C"/> as the general fallback documentation when no translation is available. * omf install part From old times, I had an `install-doc` target at hand, and in some automake project there was not even that and just some pkgdoc_DATA files around to be installed automatically. The html/xml files get installed and we are ready to register them into the systems help browsers via scrollkeeper. omfdir=${datadir}/omf pkgomfdir=${omfdir}/${PACKAGE} install-omf : $(PACKAGE)-doc.omf $(PACKAGE)-man.omf $(mkinstalldirs) $(DESTDIR)$(pkgomfdir) $(INSTALL_DATA) $(PACKAGE)-doc.omf $(DESTDIR)$(pkgomfdir)/ $(INSTALL_DATA) $(PACKAGE)-man.omf $(DESTDIR)$(pkgomfdir)/ - test ".$(DESTDIR)" != "." || scrollkeeper-update -v The last call is conditionalized with a $DESTDIR check simply for packaging traditions - you do not want to recreate a scrollkeeper index repository in the tmp-installpath used by destdir-packaging. Instead, a scrollkeeper-update call should be part of the rpm/deb package's post-install/post-uninstall specification. In a .spec file I am currently writing this: %files doc %dir %{_docdir}/%{name} %{_docdir}/%{name}/* %dir %{_datadir}/omf/%{name} %{_datadir}/omf/%{name}/* %post doc test ! -f /usr/bin/scrollkeeper-update || /usr/bin/scrollkeeper-update %postun doc test ! -f /usr/bin/scrollkeeper-update || /usr/bin/scrollkeeper-update * that's it. it's perhaps a bit a long description but at the same time it should make it most easy for you to go with it step by step and take benefit of modern help facilities for the developer/enduser html documentation. It can be as easy as the html files that you install on your project's homepage anyway - and just install/register them via scrollkeeper so that people can read/search them locally, possibly including translations. And this help system can well make you drop any `todo` for an .info file as well, in case you do not have one around up to now.... and it may well be that the whole info system becomes largely obsolete when more developer's pick up the facilities provided by omf/scrollkeeper. -- have fun, guido http://zziplib.sf.net http://ac-archive.sf.net
