autoconf
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

OT: doc install into omf/scrollkeeper


From: Guido Draheim
Subject: OT: doc install into omf/scrollkeeper
Date: Thu, 02 Jan 2003 06:49:08 +0100
User-agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.1) Gecko/20020826

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,<,\&lt;,g' -e 's,>,\&gt;,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





reply via email to

[Prev in Thread] Current Thread [Next in Thread]