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

Re: [DEP5] Asking for common wisdom on new field(s): References*



Hi Andreas,

> talks about upstream-metadata.yaml.  If you want to talk about the
> reference file you can rather move the discussion to debian-science list
> because the general Debian maintainer / user will not be very
> interested.
ok -- this will be the last one, cross-posted, following discussions on
references should occur in debian-science

On Thu, 25 Nov 2010, Andreas Tille wrote:
> The only "ready to use" format is IMHO BibTeX.  *Conversion* to BibTeX
> is cheap, but a conversion between yaml and BibTeX will be necessary
> (but easy to do with a script).
having that script ready and demoed might improve adoption

> As far as I know there is no such thing like a common format between
> different upstream sources.  The most references I have found were more
> or less free text information on web pages, sometimes in README files.
> I did not yet found a BibTeX file inside an upstream source.  So IMHO
> we rather has the situation:
>   unstructured information (used by upstream) -> UNIFIED_DEBIAN_FORMAT (used by us) -> COMMON_REFERENCE_FORMAT (used by users)
> So we definitely have
>   unstructured information != COMMON_REFERENCE_FORMAT (used by users)

I guess that is indeed the situation in ~90% (number reflects just my
"guts" feeling about how many I saw) on the other hand, R libraries (as
you pointed it out) already carry it in BibTex.  Also some upstream
packages do provide complete .bib files not only with canonical but also
with additional relevant references (e.g. ANTS, but there it was
stripped ;) and PyMVPA ;-) )


> > > http://wiki.debian.org/UpstreamMetadata
> was born and never widely accepted (because not properly published?)
or may be because is not yet usable "out-of-the-box" with no hassle (in
terms of references)? and once again, duplication, thus additional
burden for no obvious (yet) advantages

> about references only.  In this case the BibTeX formated reference file
> would be even better because it does not need further conversion.
yeap... also it would need some agreement on the IDs of the
references... I don't think they should stay original, but rather should
be based on the upstream project name with ":something" for
specialization if additional entries available, e.g.

pymvpa         -- canonical reference paper
pymvpa:manual  -- reference to user manual

this way users (if references become seamlessly available) could easily
locate necessary reference and use it without trying to recall codename
for the paper


> That's the point.  If we would drop references and provide a script
>    yaml2bibtex
> which converts upstream-metadata.yaml to references (preferably in a
> default location like
>    /usr/share/references/<package>.bib
> or something like this) and if we do this at package build time (or
> postinst??) the upstream-metadata.yaml approach would probably the
> most flexible idea.
could be indeed... but few points

* canonical references for the package(s) should be easier to find, thus
  imho should reside somewhere under /usr/share/doc/<package>/; thus
  I have sympathy for ../references.bib

* package might also ship an extended bibliography of related papers,
  that is the one which should get into

   /usr/share/references/<package>.bib

in "our" debian-bibliography (not yet obviously tried to be accepted) we
installed [1]

  /usr/share/bib/debian.bib

with canonical Debian references.  but it could become share/references
;)

* since the point is to make those canonical references also readily
  usable, we came up with dbib_collect tool [2], which upon user's
  desire could generate him a .bib file of canonical references for the
  software he has installed on the system
  (or idea also was to be able to use it on our packages.debian.org on
  extracted changelog files to generate a complete bibliography of
  canonical references for the archive)

  but if it also traversed all R packages docs, /references,
  upstream-meta, I guess it could easily become usable/useful beyond our
  'references in copyright' idea...   should I?

  having a single .bib for each single canonical reference under
  /usr/share/references/   might be less convenient, since it would
  require to add not only reference in the text but also include that
  bibliography for the sake of a single  reference....  imaging writing
  a paper overviewing software available in Debian, \bibliography line
  might become unmanageable

  now when I am to write a paper, I would just do
  
  dbib_collect > used_software.bib

  and in LaTeX have
  
  \bibliography{debian,used_software,pymvpa}

  to be able to reference Debian materials, any used software, and
  additional references relevant (and provided) to pymvpa

> have machine readable bibliographic information *now*(ish) we need to
> find another solution (which could be provided by
> upstream-metadata.yaml).

;-) we are making the same claims -- we have *now*(ish) solution as well
already ;)

> For your question what becomed left other than references?  IMHO
>   http://wiki.debian.org/UpstreamMetadata
> has some more information fields which are definitely of general
> interest.

rright, keep in mind though that

* there might be multiple "canonical" references (e.g. pymvpa,
  pymvpa:manual) depending on what really needs to be referenced for a
  particular software

* there might be multiple references, one per binary package
  (so you could have debian/package.copyright)
  since often upstream sources are collections from different
  sources.  Michael already run into such situation with data packages

both those usecases seems to need additional thought in
upstream-metadata.yaml, or am I missing some possible groupping? ;)

> >  * minimalistic debian/upstream-metadata.yaml.in just extending
> >    information from other files, not duplicating it
> YES!!
> >  * helper which generates a 'complete' debian/upstream-metadata.yaml
> >    and gets Ok'ed by Joey Hess to become a part of debhelper ;-)
> That's an interesting idea.

glad that you liked it ;-)

Cheers,

[1] http://git.debian.org/?p=pkg-exppsy/debian-bibliography.git;a=blob;hb=HEAD;f=bib/debian.bib
[2] http://git.debian.org/?p=pkg-exppsy/debian-bibliography.git;a=blob;hb=HEAD;f=tools/dbib_collect
-- 
=------------------------------------------------------------------=
Keep in touch                                     www.onerussian.com
Yaroslav Halchenko                 www.ohloh.net/accounts/yarikoptic

Attachment: signature.asc
Description: Digital signature


Reply to: