Re: document registration policy needing to be written
Many of these issues I've already addressed in my last email to you
and <debian-doc>, but there's a few new ones here.
Marco.Budde@hqsys.antar.com (Marco Budde) writes:
> I think it#s not a good idea to have two parsers like that:
>
> 0.) package calls doc-base for registration
> 1.) doc-base reads file
> 2.) produces .dhelp/dwww file
> 3.) runs dwww | dhelp
>
> I think it would be better to have something like that:
>
> 1.) package calls a wrapper script for registration
> 2.) wrapper script calls the installed system:
> for example dhelp or dwww or dhelp and dwww.
>
> The package maintainers could use something like my dhelp2dwww or we add
> dhelp support to dwww. Jim, if you need help, please email me.
I agree we should have a single documentation registration file
format; we all agree.
Here's the plan:
1) agreed upon single unified document registration file format
(called SUDRFF from here on in)
2) make it into policy
3) backwards support non-complaint packages if necessary (i.e., if
dwww and dhelp do not directly support the policy yet)
> APH> files. In that case, doc-base's install-docs system will be
> APH> useless, in fact, creating a new document control file format
> APH> without any additional purpose.
>
> That#s right. Maybe we need to improve the .dhelp format?
No, we need to eliminate it in favor of SUDRFF, if possible.
> Do we need other features? Maybe we should change the support for
> documents in foreign languages. At the moment, dhelp uses something
> like
>
> <directory>de/HOWTO
>
> Maybe it#s better to use something like that
>
> <directory>HOWTO
> <lang>de
>
> Then it would be possible, that the system admin deletes non needed
> languages from the index.
Yes a language field is would be a Good Thing (TM).
> APH> could be made 'Required' or at least reasonably standard so that
> APH> packages can register packages early on.
>
> Well, my dhelp has got a size of 30 KB :). I would suggest the following:
>
> 1.) We add .dhelp support to .dwww
> (this should be very easy)
> 2.) We add new tags to .dhelp, if we need news tags.
> 3.) We use the same section names in all packages
>
> I thing, we don#t need doc-base for the registration. We could use
> doc- base for the documentation format conversion (sgml -> ps, info,
> etc.). But still thing, that the maintainer should offer the
> documents in different formats.
I don't understand why you don't see the benefit of a small, thin,
registration system which has no coupling with any particular display
system. Do you really imagine dhelp (as good as it is) is the last
word forever and ever on document presentation? Implementation and
handling of SUDRFF, and hooking into an arbitrary set of
display/indexing systems should be the one and only purpose of
doc-base.
It's going to be hard to agree on much if I can't bringing you around
to agree on this, Marco.
> But where#s the advantage of /usr/share? For example for a package
> maintainer my solution is better, because you don#t have to create
> /usr/share/doc-base.
That's not a particularly compelling argument. I identified problems
to putting files under /usr/doc/<pkg>:
* users will be tempted to edit them directly (which is bad)
* harder to identify which packages comply with the policy
> And you can use relative paths with my solution. For
> example you could move the documents to /usr/local/doc.
That's not very compelling either. If relativity were important, we
could simply state that file paths not starting with '/' are assumed
to be relative to /usr/doc/<docid>
> And you can use my solution in a simple tar file.
?? No non-debian system will understand SUDRFF anyhow, so what's the
point of trying to support non-debian systems, if that's what you're
talking about?
> Why? Let us talk about that. dhelp uses the structure of our ftp server.
> And we have already translations to several languages.
I don't see why a document heirarchy has anything to do with language
specification. That's putting two independant bits of data in one
attribute, and it's a very bad practice.
.....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: