Re^2: document registration policy needing to be written
Am 13.04.98 schrieb apharris # burrito.onshore.com ...
APH> Many of these issues I've already addressed in my last email to you
APH> and <debian-doc>, but there's a few new ones here.
That#s right, some of these mails are a little bit out ouf date (I#ve used
the false address for the mailing list).
APH> I agree we should have a single documentation registration file
APH> format; we all agree.
That#s fine (I haven#t see a mail of Jim.)
APH> 1) agreed upon single unified document registration file format
APH> (called SUDRFF from here on in)
Well, we need a better name :). And we need a diretory structure.
APH> 2) make it into policy
Yes, that#s Christian#s part :).
APH> 3) backwards support non-complaint packages if necessary (i.e., if
APH> dwww and dhelp do not directly support the policy yet)
Not necessary for dhelp. I#ll support it as soon as possible (for slink).
APH> No, we need to eliminate it in favor of SUDRFF, if possible.
APH> I don't understand why you don't see the benefit of a small, thin,
APH> registration system which has no coupling with any particular display
Because systems like dhelp are small and I would be easier and faster
without an additional "layer".
APH> system. Do you really imagine dhelp (as good as it is) is the last
APH> word forever and ever on document presentation? Implementation and
No. It#s one way. But the parser for a file like your SUDRFF is easy to
write. So I don#t see the need for a seperate registration system (for
APH> handling of SUDRFF, and hooking into an arbitrary set of
APH> display/indexing systems should be the one and only purpose of
I#m really not sure, if this is the best solution. Where#s the advantage
of doc-base, if we have one file format?
I think the job of doc-base should be to tell systems like dhelp, that a
new package is installed and which file the program should read. And this
is difficult enough.
For example dhelp rebuilds the whole index (not the database!) if one
package is installed. This is not a good solution, if you install hundrets
of packages with dselect. It would be nice, if doc-base would call the
programs only one. For example menu seems to have a solution for this
problem (locking for dpkg#s look file?).
APH> It's going to be hard to agree on much if I can't bringing you around
APH> to agree on this, Marco.
I would suggest the following:
1.) doc-base is called for the directories including our SUD file
in postinst and prerm scripts of each package
2.) doc-base calls all index programs like dhelp/dwww, if the
file includes HTML documents
3.) dhelp/dwww read the SUD file and write an index
If we need the autoconversion: this conversion shouldn#t work during
package installation. It would be better, if the admin could call a
program "doc-base" to convert all documents of a package. And the
converted documents should *not* saved in /usr/doc.
The converted should be saved in the current directory (PS, DVI) or in
/usr/local/info (info). This would solve a lot of problems in the
connection of dpkg and doc-base.
APH> to putting files under /usr/doc/<pkg>:
APH> * users will be tempted to edit them directly (which is bad)
Why should they? And if the edit this files, this is not a problem.
I see a lot of advantages:
* easier for the maintainer, I hate to create several directories
for only one file
* no problems with file names
* it#s easier to support /usr/local/doc, relative links
* you can move a whole diretory (include documents and our file)
without changing "our file".
* you could include the file very easy in a tar archive
* maybe better, if you mount /usr/doc via NFS
APH> That's not very compelling either. If relativity were important, we
APH> could simply state that file paths not starting with '/' are assumed
APH> to be relative to /usr/doc/<docid>
But this doesn#t solve the problems, for example:
move LANG/de/HOWTO to doc-linux-de/HTML
With my solution you don#t have to change "our file".
APH> ?? No non-debian system will understand SUDRFF anyhow, so what's the
Well, maybe some other distributions will use this system in future.
APH> point of trying to support non-debian systems, if that's what you're
APH> talking about?
If your#re for example upstream and Debian maintainer of a HTML document,
you can ship "our file" in your tar archive. I don#t like files that have
to be installed in special directories.
Uni: Budde@tu-harburg.de Fido: 2:240/5202.15
Mailbox: email@example.com http://www.tu-harburg.de/~semb2204/
To UNSUBSCRIBE, email to firstname.lastname@example.org
with a subject of "unsubscribe". Trouble? Contact email@example.com