doc-base 0.4 and other issues
Well, I just uploaded a new doc-base package that solves the bugs
filed against the package and adds "dhelp support that doesn't suck".
See the changelog for details.
We have two major policy issues to solve immediately (although it is
definatly too late for hamm, of course):
(a) standardize document registration format
(b) standardize document display heirarchy / index
I feel it's most important to build consensus and whip up some
documents explaining these two issues right now. As the doc-base
maintainer, I shall take it upon myself to formulate the document (a),
unless anyone has a valid objection to that. BTW I'm going to make it
a separate SGML document, fold it out of the doc-base (but include it,
isn't SUBDOC wonderful?).
I do not intend to be the one to formulate the index scheme.
With respect to the proposed document heirarchy, I agree with Manoj in
that the document should be more of an index than a table of contents.
Furthermore, as an index, we need to allow crosslinking, in other
words, a single document id may appear in multiple locations along the
index. I personally feel unhappy with every proposed heirarchy:
Christian's is too deep; Marco's is too arbitrary. I am wondering who
if anyone here has done their homework: have we looked at FreeBSD's
heirarchy? At what we could borrow from the Dewey Decimal System?
Are there other standards out there we could borrow from?
With respect to (a), these are the issues on which I invite comment:
(a.1) I agree we should have HTML markup allowed in some fields, i.e.,
description. We need to think whether we are going to have to define
a subset of HTML to protect the overall integrity of the display side.
(a.2) Do we need any additional fields?
(a.3) Should we reconsider the 'document-id' system (one docid per
file, many formats)? Wouldn't it make it easier for package
maintainers to have a single file that could have multiple
document-ids? Would this be a bad idea?
(a.4) What file location is going to work given, say, a shared,
NFS-mounted /usr?
.....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: