On Sun, 2008-10-12 at 14:20 +0200, Michael Banck wrote:
> On Wed, Oct 08, 2008 at 08:19:25AM +0200, Andreas Tille wrote:
> >> The format of /usr/doc/package/references could be a popular one, for
> >> instance BibTeX, if it allows cross references to other systems like
> >> DOI, PubMed, ...)
> >
> > I would strongly vote for RFC822 format (as debian/control, Packages
> > and Sources file). There are tools inside Debian to work on this
> > format (I'm using these in my scripts) and conversion to any other
> > format like BibTeX would be easy.
>
> First off, I think "citation" would be a better name than "references",
> at least for the canonical reference to cite when using that package.
>
> That said, those citations are usually (or at least often) *not*
> bibliographical references to some published article, but are in the
> rought form "PACKAGE VERSION AUTHORS (INSTITUTION) YEAR", so rather
> free-form.
I agree. BibTeX and similar systems are much more structured metadata
formats, and it is *much* easier to convert from those to text than the
other way around (which is impossible in the general case).
> Another matter are the article references explaining the package and/or
> giving more information; for those, bibtex entries probably make a lot
> of sense. On the other hand, we could just have it be a list of URLs,
> either to http://dx.doi.org/<DOI> or
> http://www.ncbi.nlm.nih.gov/pubmed/<PMID> or similar. This would be a
> very compact form for a X-References in debian/control. If we settle on
> a debian/references (next to a debian/scitation), Quoting the title of
> the papers in ASCII transcription(?) (and possibly the author names),
> followed by the URL and maybe the bibtex data.
>
> Additionally, we could settle on some standard introduction text, like
> "$PACKAGE should be cited as follows:" for debian/citation and
> "Additional information for $PACKAGE can be found in the following
> publications" for debian/references.
The Description is obviously the wrong place for this, it bloats
Packages etc. And adding a new dh_addcitation would be a lot of work,
moving us to squeeze+1.
So why not just adapt the existing doc-base format, adding a new "BibTeX
files" field? The description of which citation to use when (canonical
article(s) for different parts of the package, background theory,
related stuff) can just go in the doc-base abstract.
This way, all the package needs to have is a doc-base file, which is
backward compatible (older versions of dhelp etc. will just ignore these
BibTeX files) and somewhat future-proof. With this info, a future dhelp
might create a centralized /usr/share/doc-base/references.bib file which
merges all of them, so a .tex paper need only include this file to have
access to all of the citations. And "doi = {10.1234/my_article}" can
just be a field in the .bib file, which a .bib browser can convert to an
HTML link.
Do we need any more metadata than this? Is there anything you can
envision a dh_addcitation doing beyond this? For some reason is the
doc-base file not an appropriate place to put it?
-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