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

Re^2: document registration policy needing to be written

Am 13.04.98 schrieb apharris # burrito.onshore.com ...

Moin Adam!

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
APH> doc-base.

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.

cu, Marco

Uni: Budde@tu-harburg.de           Fido: 2:240/5202.15
Mailbox: mbudde@hqsys.antar.com    http://www.tu-harburg.de/~semb2204/

To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org

Reply to: