[FHS] doc compiled by postinst
Dear mentors,
I want some documentation for my packages to be compiled during
postinst and I am wondering were the best place to store this
documentation is.
Rationale:
This issue come up for the yorick* packages. Yorick is an interpreted
language, and I have packaged several add-on packages. The upcoming
release of Yorick is able to compile cross-referenced and indexed
HTML documentation from its library of interpreted files. My goal is
to provide HTML documentation for all the yorick commands installed
on the system in a central location.
The solution on which I am settling is to build this documentation
during postinst by the main package as well as by each add-on package
(as well as during postrm). So at any time, the documentation (in
particular the index files) are in sync with what functionalities are
actually available on the system.
Question:
I have a vague impression that I should not rely on /usr/share/doc
containing the files I need or even existing during postinst. In
fact, I think I remember having read that the system should still
function perfectly if the admin decides she wishes to delete /usr/
share/doc.
This likely means that I need to put any _source_ file for this
compilation somewhere else, but I'm not sure where to put the
compiled doc. I see 4 possibilities:
1) in /usr/share/doc/yorick-data/, were the rest of the Yorick
documentation is. But this directory belongs to yorick-data, and I'm
not sure whether it's OK for the scripts of packages to modify it.
2) in a dedicated directory under /usr/share/doc/, e.g. /usr/share/
doc/yorick-doc/ (assuming there is no yorick-doc package).
3) in /usr/share (this is the option I have chosen so far: the doc
is built in /usr/share/yorick/doc, side-by-side with the Yorick code
it documents).
4) somewhere in /var, because this is somewhat "variable", but I
believe /var is for stuff that varies outside of installation/upgrade/
uninstallation sessions.
So far, I build this doc in /usr/share/yorick/doc/html_xref, and
there is a link in /usr/share/doc/yorick-data which points there.
Conversely, there are links in /usr/share/yorick/doc/ which point to
the static documentation in /usr/share/doc/yorick-data, because
that's were upstream puts it (so some users and utility scripts will
look for it there). Each yorick add-on may provides a few files in /
usr/share/yorick/doc/src/ to improve the way it is listed in the
high level index files.
Best regards, Thibaut.
Reply to: