On Thu, 2008-10-16 at 21:36 +0200, Manuel Prinz wrote:
> Am Donnerstag, den 16.10.2008, 17:41 +0200 schrieb Michael Banck:
> > The problem I have with doc-base is that it is underused and not very
> > accessible. At least that is my impression of it as somebody who
> > doesn't care a lot about it from a packager's POV. I probably should
> > care more, though.
>
> I know lots of long-term Debian users who are not even aware of doc-base
> at all... I do share your POV here.
Really? But doc-base is so cool! It's yet another Debian invention
(predates scrollkeeper by several years) which makes life a ton easier
for users, like apt and debconf.
> > So anyway, I'd really like to have something usable for users in
> > /usr/share/doc/<package> and not just some meta-data stream that's
> > marked up reasonably somewhere else. Maybe it's best to have a seperate
> > citation.bib and references.bib file with just the bibtex data?
>
> This is IMHO the solution to go for. Adam's idea is quite good as well,
> and as I see it, they're complementary in that we could use doc-base for
> now and use the data (better: the .doc-base files) to generate the
> citations.bib and references.bib out of those entries via a script.
My idea was actually to have the citations.bib and/or references.bib
in /usr/share/doc/<package> as you say, and have the .doc-base file
include something like:
Format: BibTeX
Files: /usr/share/doc/<package>/*.bib
Is there an advantage to having the BibTeX data right in the .doc-base
file? I can't see one, and I think it might confuse .doc-base parsers.
So I think we agree about this. Advantages:
* It uses (and perhaps reinforces) the doc-base index system,
which IMO is one of Debian's under-appreciated strengths.
* It's backward-compatible with old versions of debhelper,
dhelp/dwww, etc. which will just ignore that section
of .doc-base.
* There's a user-visible place for .bib files, which is wherever
the maintainer feels is the best place for them, we don't need
to wait for a script to be available to generate it.
* Metadata are in one place, which is the .bib files, not
duplicated in .doc-base and .bib files and plain formats and
HTML and control, so the maintainer only has to change or update
things once.
* It doesn't bloat Packages or control.
* It's future-expandable, as new versions of dhelp etc. can use
the .doc-base and .bib files to generate a whole host of new
user- friendly files, from a master .bib file or other reference
manager files, to a plain text reference list, to an HTML index
with links to the DOIs.
* Scrollkeeper might follow Debian's leadership (again) and make
use of such metadata.
-Adam
--
GPG fingerprint: D54D 1AEE B11C CE9B A02B C5DD 526F 01E8 564E E4B6
Engineering consulting with open source tools
http://www.opennovation.com/
Attachment:
signature.asc
Description: This is a digitally signed message part