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

Re: Documentation registry

Wichert Akkerman <wichert@mors.wiggy.net> writes:

> Previously Adam Di Carlo wrote:
> > [Can we redirect this to debian-doc list please?]
> Did debian-doc become a list where more is discussed then writing
> documentation now? 


> If so I'll need to subscribe to yet-another-list :(

Yes, well, can I unsub from debian-devel ?

It's 98% noise for me, but I like picking out the threads.

> > This is addressed in my plans for doc-base 1.x,
> > <URL:http://www.debian.org/~aph/debian-metadata.html/>.
> Not to be annoying, but how much change has that of becoming a reality
> in lets say woody? I haven't seen any changes in doc-base in ages and
> as I said the current design seems to wrong to me that I figured we
> might as well give up on it.

I don't mind.  You're correct to point it out.

Even if I'm not the one to do it, why not build on it?

I admit I haven't done shit with it, but maybe if other can take over
my other packages, such as jade, openjade, developers-reference, an
upstream developer for sgml-data, etc., then I should be able to do

Or if I get volunteers....  Any volunteers?

> > How to really handled i18n'd data is a tough tough issue though.  Most
> > people don't want it on their machine if they don't speak it.
> That's an orthogonal issue imho. If its there it should be registered.
> If not, then not.
> > Others point out stepping on files at, say, document registration time is not
> > a good plan in case you change your mind later (how to reinstall all
> > the missing data?).
> I'm not sure what you mean here. If using seperate registrion-files like
> the menu system,

No, I was talking about, say, if you had local preferences to only
have english documentation, then if it saw some German stuff get
registered, it could, possibly, auto-remove that.  But that's a tricky
issue (partial pkg installations).

> modutils or mime-support uses its a simple matter of calling
> update-something. Personally I find that a *much* saner approach
> then calling install-something each time for for each document.

I don't agree.  You just say it's saner but now why.  I pointed out
some reasons why it is preferable to keep metadata in the document
itself.  But your system would eliminate that possibility.

The fact is we just need two types of data stored:

  - what documents have registered (filename list)

  - all the metadata we have collected from the documents which have 

The only benefit to /usr/share/doc-base is that we could (but
currently don't) pick up all the metadata prior to doc-base being
installed.  I think a better solution is simply to put doc-base in
base, and make it required (well, when it's done).

> If the registritation software needs to know what has changed it
> should keep its own list of what it already saw.

It will.

> > Any coders volunteer to help me implement (should be Perl, I think)?
> Personally I'm moving away from the illogical beast that is perl towards
> python, however whoever implements it should choose that for himself.
> > I plan to do this as a Dublin Core metadata set (see the document).
> > It should be possible to put metadata in the headers of SGML or HTML
> > files and just use that, not even needing separate metadata
> > descriptions.
> Eww, that means that you can only handle documents in a fixed list of
> places.

Huh?  Not at all.  You don't understand.  My plan was that we could
use the metadata in the head of /usr/share/doc/foo/foobar.html, or we
could use a special separate docreg file, if you wanted to.
Obviously, if the HTML is already coming from upstream with the proper
metadata, then that's good and we should allow the pkg maintainer to
use that with no fuss.

> > I don't like the idea of the files req'd in /usr/share/... because
> > that discourages use of metadata in source document headers, and
> > discourages /usr/local use of the system.
> It doesn't discourage it, it should be trivial to extract that metadata
> in debian/rules and create the registration-files from that.

Yes, but what about local sysadmins wanting to register local
documentation on a system, documentation which is not *in* a package?

> > The system must be back compat.
> The current system isn't used enough for me to really care about that,
> it should be pretty easy to switch. And switch people will, since I'm 
> kind of planning on ditching the current install-info and make it generate
> the dir-file based on these registration files.

A common attitude in Debian, but one I disagree with.

.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>

Reply to: