tasks overview wishlist: Canonical citing reference

[Michael Banck]

Hi,

One thing I'd like to have added to the nice package overviews at
http://cdd.alioth.debian.org/science/tasks/chemistry.html etc. is a
canonical reference which should be given in scientific papers using
that package.

On the one hand, this is mandated by some (non-free) packages already,
on the other hand, it is good scientific practise and would be nice to
have better exposed and centrally available.

E.g, for mpqc, this would be (see http://www.mpqc.org/pub.php)

"The Massively Parallel Quantum Chemistry Program (MPQC), Version
2.3.1, Curtis L. Janssen, Ida B. Nielsen, Matt L. Leininger, Edward F.
Valeev, Joseph P. Kenny, Edward T. Seidl, Sandia National Laboratories,
Livermore, CA, USA, 2008"

I don't think this belongs into the package description, but maybe as a
X-* field in debian/control post-lenny.  For lenny, we could add a
field/comment in some svn repository (not sure from what sources those
nice overviews are generated).

Also, having this would sense a clear signal to upstream authors that we
consider proper citing important and that enforcing citations in
copyright licensing is not the best thing to do.


A second thing would be to optionally add the DOI (or maybe the full
reference, not sure) of one or a couple (not too many, obviously) papers
describing the package, if there is any.  Sometimes, this might be the
same reference as the canonical citing reference, but usually not.  The
DOIs could then be written as http://dx.doi.org/<DOI> links for easy
access (though I'm not sure what to write as link text, maybe the
reference text as would be given in a paper)

Again, for MPQC, this would be

DOI:10.1088/1742-6596/46/1/031, DOI:10.1002/jcc.20815


What do you think?


Michael


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

Hi!

I like the idea. It makes software look more seriouse. Could happen that your
software gets citations on sites like citeseerx.ist.psu.edu if used
consequently :-)

Nik



Am Dienstag, 7. Oktober 2008 schrieb Michael Banck:

> Hi,
>
> One thing I'd like to have added to the nice package overviews at
> http://cdd.alioth.debian.org/science/tasks/chemistry.html etc. is a
> canonical reference which should be given in scientific papers using
> that package.
>
> On the one hand, this is mandated by some (non-free) packages already,
> on the other hand, it is good scientific practise and would be nice to
> have better exposed and centrally available.
>
> E.g, for mpqc, this would be (see http://www.mpqc.org/pub.php)
>
> "The Massively Parallel Quantum Chemistry Program (MPQC), Version
> 2.3.1, Curtis L. Janssen, Ida B. Nielsen, Matt L. Leininger, Edward F.
> Valeev, Joseph P. Kenny, Edward T. Seidl, Sandia National Laboratories,
> Livermore, CA, USA, 2008"
>
> I don't think this belongs into the package description, but maybe as a
> X-* field in debian/control post-lenny.  For lenny, we could add a
> field/comment in some svn repository (not sure from what sources those
> nice overviews are generated).
>
> Also, having this would sense a clear signal to upstream authors that we
> consider proper citing important and that enforcing citations in
> copyright licensing is not the best thing to do.
>
>
> A second thing would be to optionally add the DOI (or maybe the full
> reference, not sure) of one or a couple (not too many, obviously) papers
> describing the package, if there is any.  Sometimes, this might be the
> same reference as the canonical citing reference, but usually not.  The
> DOIs could then be written as http://dx.doi.org/<DOI> links for easy
> access (though I'm not sure what to write as link text, maybe the
> reference text as would be given in a paper)
>
> Again, for MPQC, this would be
>
> DOI:10.1088/1742-6596/46/1/031, DOI:10.1002/jcc.20815
>
>
> What do you think?
>
>
> Michael

--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Bernhard R. Link-2]

* Michael Banck <mbanck@...> [081007 22:53]:
> Also, having this would sense a clear signal to upstream authors that we
> consider proper citing important and that enforcing citations in
> copyright licensing is not the best thing to do.

I think the better signal to send is that "enforced citation" is
considered not academical behaviour as it is simply citation trolling.
I my eyes it is equivalent of paying people to cite you. (Or rather
eqauivalent to harrassing people to make them cite you).

There might be things where software can actually be used as academical
contribution to some paper, but all examples I've yet seen were just
ridicilously broad. Neighter your calculator nor your typewriter belonged
in the citations (though sometimes might have been added as kind of joke,
like people trying to award PHDs to their desktop computer), not does
the equivalent in software. Citations have an academic purpose, they are
not something to collect to make your resume look better...

        Bernhard R. Link


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Steffen Moeller-3]

Michael Banck wrote:
> One thing I'd like to have added to the nice package overviews at
> http://cdd.alioth.debian.org/science/tasks/chemistry.html etc. is a
> canonical reference which should be given in scientific papers using
> that package.
>  
I agree. Many placed respective indications in the package description of
the debian/control file. Would there be objections for a dedicated X-pub
field
there of some sort?

Steffen


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Michael Banck]

On Tue, Oct 07, 2008 at 11:55:34PM +0200, Bernhard R. Link wrote:

> * Michael Banck <mbanck@...> [081007 22:53]:
> > Also, having this would sense a clear signal to upstream authors that we
> > consider proper citing important and that enforcing citations in
> > copyright licensing is not the best thing to do.
>
> I think the better signal to send is that "enforced citation" is
> considered not academical behaviour as it is simply citation trolling.
> I my eyes it is equivalent of paying people to cite you. (Or rather
> eqauivalent to harrassing people to make them cite you).
>
> There might be things where software can actually be used as academical
> contribution to some paper, but all examples I've yet seen were just
> ridicilously broad. Neighter your calculator nor your typewriter belonged
> in the citations (though sometimes might have been added as kind of joke,
> like people trying to award PHDs to their desktop computer), not does
> the equivalent in software. Citations have an academic purpose, they are
> not something to collect to make your resume look better...

Well, it's not that black/white.  For many independent researchers, a
citation count might be a good estimate that the grant money they get is
well spent etc.

In the above, I assumed that we were talking about scientific packages,
not random Debian packages like vi.  

Certainly, the citation mannors might be different in the various fields
of science, but at least in some fields, if you use a software package
to create scientific data you publish, you should cite that package.
Now, whether that is a SHOULD or MUST and how it is encoded in
etiquette/copyright/trademark/whatever law/rules is differing.

But I think pointing out an approriate citation is better than waiting
for authors to enforce it.


Michael


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Charles Plessy-12]

Hi Michael,

I fully support the idea of providing a proper reference to the software
we distribute. In Debian-Med, I put one in the packages's description,
but I am not completely satisfied with this because:

 - In some case, more than one would be necessary, and it would overload
   the description.
 - I did not follow strict formattign rules, which is not too helpful for
   people who want to use citation managers.
 - As you wrote, it does not belong to the description anyway ;)

You propose an additional control field for after Lenny release, but my
gut feeling is that there will be a strong opposition on
debian-devel@..., as extra fields make some files such as Packages.gz
heavier, which is a disadvantage for platforms with limited CPU power,
that have to parse this file despite not being likely to use this
feature.

Maybe we can separate two issues:

 - Providing proper citations to the users of our packages.
 - Providing proper citations to the people browsing our task pages.

We could for instance settle on a format and simply start to
provide references in /usr/doc/package/references. This would already be
directly useful. When enough will be accumulated, we can thing about
some mechanisms that would use those references to keep a central file
up to date, that people could directly use with their reference
managers. This would add convenience. For the task webpages, if the
information is not in the Packages.gz file, it makes things a bit more
complicated. Maybe after establishing /usr/doc/package/citation we could
have a script that reads those files from the VCS repositories we use ?

With this approach we can start as soon as we agree on a mode of
operation, keep the things very simple at the beginning, and develop the
system as it gains popularity.

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, ...)

Have a nice day,

--
Charles Plessy
Debian Med packaging team,
Tsurumi, Kanagawa, Japan


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Ben Burton]

> There might be things where software can actually be used as academical
> contribution to some paper, but all examples I've yet seen were just
> ridicilously broad.

FWIW, it's not uncommon in my field (discrete mathematics).  In particular,
there are proofs that rely on very large but finite case bashes, and these
are often done with the help of a computer (in particular, mathematical
software).  In this sense, the software contributes directly to the proof
of a theorem.

b.


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Rudi Cilibrasi, Ph.D.]

Most of my peer reviewed published research papers involve the software in the
complearn package.  I (and some others) do wind up citing it fairly often FWIW.
Best regards,

Rudi

On Tue, Oct 7, 2008 at 7:32 PM, Ben Burton <bab@...> wrote:

>
>> There might be things where software can actually be used as academical
>> contribution to some paper, but all examples I've yet seen were just
>> ridicilously broad.
>
> FWIW, it's not uncommon in my field (discrete mathematics).  In particular,
> there are proofs that rely on very large but finite case bashes, and these
> are often done with the help of a computer (in particular, mathematical
> software).  In this sense, the software contributes directly to the proof
> of a theorem.
>
> b.
>
>
> --
> To UNSUBSCRIBE, email to debian-science-request@...
> with a subject of "unsubscribe". Trouble? Contact listmaster@...
>
>

--
Git, Hg (Mercurial), and Subversion (svn) hosting over SSH
http://sshcontrol.com/


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Andreas Tille]

On Tue, 7 Oct 2008, Michael Banck wrote:

> One thing I'd like to have added to the nice package overviews at
> http://cdd.alioth.debian.org/science/tasks/chemistry.html etc. is a
> canonical reference which should be given in scientific papers using
> that package.

ACK

> I don't think this belongs into the package description, but maybe as a
> X-* field in debian/control post-lenny.

IMHO this is a reasonable solution because it enables a clear way to
obtain this information in a structured manner.

> For lenny, we could add a
> field/comment in some svn repository (not sure from what sources those
> nice overviews are generated).

Well, a hackish solution would be to add this field to the tasks files.
That would be quite easy to implement but is available only in the
tasks overview and nowhere else (well, in principle there is a chance
to move the information to some place if you are using the meta packages
and we somehow propagate the information from the tasks files to the
binary meta package to a defined place this is also somehow possible
but not really nice (= hackish) and I would wait with implementing this
until the cdd-dev tools are rewritten (which has to be done anyway because
of an Arch: all/any issue which is completely unrelated to this topic
here but it needs a rewrite anyway and we could regard such kind of
stuff easily then).

I could imagine for example inside task bio:

   Depends: clustalw
   References: "Clustal W and Clustal X version 2.0", Larkin M., et al.
               Bioinformatics 2007 23(21):2947-2948

which might be moved below the package descriptions as "References".
You could use the normal formatting of debian/control files with item
lists.  The drawback of this easily to implement hack I see immediately
that you have to remove the reference from the description first (=reupload
the binary) because mentionien references twice locks just stupid.  So
we have to touch the package anyway (in case a reference is mentioned
in the description).  That's why I would not really prefer this which
has several other drawbacks.  IMHO the only reasonable case where we
could just test this reference feature is to add references in the
suggested structured way to prospective packages which do not have any
information in Debian Packages files.

> Again, for MPQC, this would be
>
> DOI:10.1088/1742-6596/46/1/031, DOI:10.1002/jcc.20815

Same as above for References.

Kind regards

         Andreas.

--
http://fam-tille.de


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Andreas Tille]

On Wed, 8 Oct 2008, Charles Plessy wrote:

> I fully support the idea of providing a proper reference to the software
> we distribute. In Debian-Med, I put one in the packages's description,
> but I am not completely satisfied with this because:
>
> - In some case, more than one would be necessary, and it would overload
>   the description.
> - I did not follow strict formattign rules, which is not too helpful for
>   people who want to use citation managers.
> - As you wrote, it does not belong to the description anyway ;)
>
> You propose an additional control field for after Lenny release, but my
> gut feeling is that there will be a strong opposition on
> debian-devel@..., as extra fields make some files such as Packages.gz
> heavier, which is a disadvantage for platforms with limited CPU power,
> that have to parse this file despite not being likely to use this
> feature.

I see to arguments against these "disadvantage".

   1. If people start putting the References into the long description
      it is moved to the Packages file anyway.  So giving the information
      in an extra field will not add a considerable amount of bytes to
      the packages field.
   2. For those "limited CPU powers" architectures you might even
      consider to remove the References field from the Packages file
      which means you are even gaining something by providing the
      information in a structured way.

> Maybe we can separate two issues:
>
> - Providing proper citations to the users of our packages.
> - Providing proper citations to the people browsing our task pages.

OK, this is a reasonable distinction.  For the last item I like to
add the comment that I do not really like the focus on the task pages.
IMHO the task pages are just another view onto the Debian package
pool.  So there should be no extra information than you can get
via apt-cache or synaptic (at least for those packages inside the
pool) - it is rather a "nice selection" out of the large pool.  That's
why I called the possible hack for the tasks files as hackish in
my previous mail.

Regarding your first item we might think about a debian/references
file with a defined structure and write a dh_installreferences script
to move this information to a defined place.  I'm not really sure
whether this is overdesign for a use in a number of packages which
is of order 100 or so - but this idea came to my mind.  If our
attempt to add the information to the Packages files we could use
just another way to move the information straight to the tasks pages
(even if I would prefer the contro file solution):

    References: svn://svn.debian.org/<path_to_packaging>/debian/references

Parsing the content of this references file should be some kind of
plan B compared to the X-* solution in debian/control.

> We could for instance settle on a format and simply start to
> provide references in /usr/doc/package/references. This would already be
> directly useful. When enough will be accumulated, we can thing about
> some mechanisms that would use those references to keep a central file
> up to date, that people could directly use with their reference
> managers.

That's why I would use dh_installreferences.  The script could be
easily changed to handle the structured information and packaging
stuff needs not to be changed.  Such a script could even work on
X-* fields in debian/control.

> This would add convenience. For the task webpages, if the
> information is not in the Packages.gz file, it makes things a bit more
> complicated. Maybe after establishing /usr/doc/package/citation we could
> have a script that reads those files from the VCS repositories we use ?

IMHO a central sitation file is hard to manage.  I would prefer the
per package information suggested above - but perhaps I have to think
twice.

> 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.

Kind regards

        Andreas.

--
http://fam-tille.de


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Teemu Ikonen-2]

On Wed, Oct 8, 2008 at 2:27 AM, Charles Plessy <plessy@...> wrote:
> You propose an additional control field for after Lenny release, but my
> gut feeling is that there will be a strong opposition on
> debian-devel@..., as extra fields make some files such as Packages.gz
> heavier, which is a disadvantage for platforms with limited CPU power,
> that have to parse this file despite not being likely to use this
> feature.

I also think that the argument against extra fields in control is a
strong one, unless there are already tools to filter the Packages file
to contain just the fields which are technically necessary to the
packaging system. One must fight bloat in all fronts :)

> Maybe we can separate two issues:
>
>  - Providing proper citations to the users of our packages.
>  - Providing proper citations to the people browsing our task pages.

How about adding an extra field to the machine readable copyright file
format? The mr-copyright file is RFC822 and thus easy to parse, and is
already in every Debian package. Package users could find the citation
from the same place as other author, copyright and licensing info. As
could the program generating task pages and other package listings.

The downsides are that packages could not be found by grepping or
apt-cache search:ing the reference from the Packages file, and that
putting a citation to 'copyright' file would send a weak signal that
having licenses which require citation would be somehow socially
acceptable, which it is not.

Teemu


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Adam C Powell IV]

On Tue, 2008-10-07 at 23:55 +0200, Bernhard R. Link wrote:
> * Michael Banck <mbanck@...> [081007 22:53]:
> > Also, having this would sense a clear signal to upstream authors that we
> > consider proper citing important and that enforcing citations in
> > copyright licensing is not the best thing to do.
>
> I think the better signal to send is that "enforced citation" is
> considered not academical behaviour as it is simply citation trolling.
> I my eyes it is equivalent of paying people to cite you. (Or rather
> eqauivalent to harrassing people to make them cite you).

I disagree.  Papers are required to provide full details on the methods
they use which affect the results, whether an instrument or piece of
software.  That provides transparency and verification.  For example, if
someone package A version B.C to solve equation Y, and someone else gets
a different solution, and a third person later finds a bug in that
version, it is essential to have the software and version in the papers
in order to sort out who is write.  The citation provides the canonical
reference to the software.

To address another side of this, the relevant currency in academia is
credit and not money, and nobody is paying or harassing anyone to use a
piece of software.  If you don't want to cite it, use a different tool,
or re-implement it.  But using software without citing it is like not
citing an algorithm or experimental method.

> There might be things where software can actually be used as academical
> contribution to some paper, but all examples I've yet seen were just
> ridicilously broad. Neighter your calculator nor your typewriter belonged
> in the citations (though sometimes might have been added as kind of joke,
> like people trying to award PHDs to their desktop computer), not does
> the equivalent in software. Citations have an academic purpose, they are
> not something to collect to make your resume look better...

That's a completely different situation.  One doesn't need to cite the
make and model of computer, as long as computers can be trusted to do
math properly -- the Pentium fdiv bug being the only counterexample I
know of in the past 30 years or so.

Until scientific software is as reliable and robust as arithmetic in
silicon (or the libm for that matter), we'll need to cite it properly.

-Adam
--
GPG fingerprint: D54D 1AEE B11C CE9B A02B  C5DD 526F 01E8 564E E4B6

Engineering consulting with open source tools
http://www.opennovation.com/

[Bernhard R. Link-2]

* Michael Banck <mbanck@...> [081008 00:28]:
> Certainly, the citation mannors might be different in the various fields
> of science, but at least in some fields, if you use a software package
> to create scientific data you publish,

The important part here is what means "use a software package to create
scientific data you publish"?

In broad terms that would include the kernel you use (you can hardly
produce data without), your editor, the compiler you used to compile
your programs into binaries, the xcalc you used to check the numbers
sum up, and so on.

I do not see why that should be different for example for the
typesetting package or the computer algrebra system you use to do
some matrix inversions.

Hochachtungsvoll,
        Bernhard R. Link


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Charles Plessy-12]

Le Wed, Oct 08, 2008 at 04:11:26PM +0200, Bernhard R. Link a écrit :
>
> I do not see why that should be different for example for the
> typesetting package or the computer algrebra system you use to do
> some matrix inversions.

Hi,

If we do not cite software made by academic developers, they will not
get a good evaluation and eventually lose their funding or even their
jobs. Pressure is high enough that some do not want to be packaged
because it lowers their download counter, which is another metric for
evaluation.

I write it caricaturally, but when authors ask to be cited, it is not
for vanity but for professional survival. Luckily, whith the advent of
electronic publication, there are less limits on the number of
references per article.

In the end, if people really prefer to work with this or that kernel, I
would not be shocked if it were mentinned somewhere in the article,
similarly to rock bands that indicate what gutar strings they use :)


Have a nice day,

--
Charles Plessy
Debian Med packaging team,
Tsurumi, Kanagawa, Japan


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Bernhard R. Link-2]

* Charles Plessy <plessy@...> [081008 16:28]:
> [...], but when authors ask to be cited, it is not
> for vanity but for professional survival.

Sorry if that sounds harsh: But when people fake their results, they
sometimes do not do so for vanity but for survival, too.

> Luckily, whith the advent of
> electronic publication, there are less limits on the number of
> references per article.

So making citations less meaningfull by just adding everything or
even trying to pressure people into making unmeaningfull citations
is less bad?

> In the end, if people really prefer to work with this or that kernel, I
> would not be shocked if it were mentinned somewhere in the article,
> similarly to rock bands that indicate what gutar strings they use :)

Nothing bad about mentioning things that might make some reading less
boring, but additional thanks and mentioning of things not needed for
the verfication or scientific surroundings of an paper is really only
up to the author.

Hochachtungsvoll,
        Bernhard R. Link


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Charles Plessy-12]

Le Wed, Oct 08, 2008 at 08:19:25AM +0200, Andreas Tille a écrit :
>
> Regarding your first item we might think about a debian/references
> file with a defined structure and write a dh_installreferences script
> to move this information to a defined place.

> 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.

Le Wed, Oct 08, 2008 at 11:24:10AM +0200, Teemu Ikonen a écrit :
>
> How about adding an extra field to the machine readable copyright file
> format? The mr-copyright file is RFC822 and thus easy to parse, and is
> already in every Debian package. Package users could find the citation
> from the same place as other author, copyright and licensing info. As
> could the program generating task pages and other package listings.

Hi all,

I have no strong opinion where to put the bibliographic information, and
propose to discuss the different possibilities on debian-devel once we
have brainstormed enough.

For the format, although I won't stop volunteers to write conversion
scripts, I would like to stress out that for biology the easiest is
probably do download the pubmed.org record and convert it using the
bibutils package in Debian, and that if we do not use a well recognised
format, the first thing users will do is probably to reconvert what we
provide to either PubMed, BibTeX or Endnote formats...

When we will have enough references, having a debhelper script will
definitely be a nice enhancement. I also see it as a long term goal, as
it will take one release cycle to have it in Stable. Using it before can
complicate user backports.

Have a nice day,

--
Charles Plessy
Debian Med packaging team,
Tsurumi, Kanagawa, Japan


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Steffen Moeller-3]

Hello,

Charles Plessy wrote:

>
> I have no strong opinion where to put the bibliographic information, and
> propose to discuss the different possibilities on debian-devel once we
> have brainstormed enough.
>
> For the format, although I won't stop volunteers to write conversion
> scripts, I would like to stress out that for biology the easiest is
> probably do download the pubmed.org record and convert it using the
> bibutils package in Debian, and that if we do not use a well recognised
> format, the first thing users will do is probably to reconvert what we
> provide to either PubMed, BibTeX or Endnote formats...

I am with Charles. What I particularly like about this thread that it
is not about getting singular packages out but about how Debian
integrates best with the users as an hollistic instrument.

Steffen


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Manuel Prinz-2]

Hi all!

> Le Wed, Oct 08, 2008 at 08:19:25AM +0200, Andreas Tille a écrit :
> > Regarding your first item we might think about a debian/references
> > file with a defined structure and write a dh_installreferences script
> > to move this information to a defined place.

I prefer this solution of using a seperate file under ./debian since --
as Charles already said earlier -- there will be some opposition on
debian-devel. I'm involved with some (though little) of the "limited CPU
power" things and have quite strong feelings about adding a new field to
Packages since this file already grows to large. It's also mostly not an
issue of CPU power but bandwidth and disk space, as there are no tools
that allow a stripped download of that file, leaving the "uninteresting"
things out.

The solution proposed by Andreas here is IMHO the way to go: Provide the
information in the source package and install them where it is needed or
wanted. This is i.e. one way the Emdebian project slims it's packages:
Not calling certain debhelper scripts. I really do not see a need to
have citations in the Packages file since this is supposed to give short
information about the package; enough to see if it might be useful, not
everything that is available.

Another thing I'd like to address is translation: If we keep the
references in the long discription -- very bad, IMHO -- we add extra
burdon on the translators. Since there is no agreement on citation
style, everything will divert and changing it to a common format will
drive translators nuts since they get informed about changes that are in
fact no real changes; but they need to process them anyway.

> > 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.

Am Donnerstag, den 09.10.2008, 10:54 +0900 schrieb Charles Plessy:
> For the format, although I won't stop volunteers to write conversion
> scripts, I would like to stress out that for biology the easiest is
> probably do download the pubmed.org record and convert it using the
> bibutils package in Debian, and that if we do not use a well recognised
> format, the first thing users will do is probably to reconvert what we
> provide to either PubMed, BibTeX or Endnote formats...

For the format, I do not really care but tend to suggest BibTeX since it
can be read from everything I know and can be directly used if one uses
LaTeX. It's also well understood by Bibus. It can also be easily
converted to other formats.

As a real fan of RFC822, I like Andreas suggestion, but I'm not what we
are going / want to provide: If it's just information about scientific
papers, I suggest to go for a format which is well understood and simply
supply it, so users can intregrate them in their bibliography software.
If we want to supply a database of all references to software inside
Debian in several formats, we needs to automatically build and maintain
this database. Also, I do not see the need to have such a database since
the single BibTeX file are enough to work with. I'd also (as a user) not
need them in BibTeX, EndNote, PubMed and whatever else is common.

> Le Wed, Oct 08, 2008 at 11:24:10AM +0200, Teemu Ikonen a écrit :
> > How about adding an extra field to the machine readable copyright file
> > format? The mr-copyright file is RFC822 and thus easy to parse, and is
> > already in every Debian package. Package users could find the citation
> > from the same place as other author, copyright and licensing info. As
> > could the program generating task pages and other package listings.

I feel like this would just suggest that citation is enforced which in
most cases it isn't. I see citation totally distinct from copyright, so
I think it's not the place where this information should go.

> When we will have enough references, having a debhelper script will
> definitely be a nice enhancement. I also see it as a long term goal, as
> it will take one release cycle to have it in Stable. Using it before can
> complicate user backports.

Sure. So, to summarize, we have the following options:

     1. The references are added to the long description
     2. The references are added to Packages via a new X-* field
     3. The references are added to debian/copyright
     4. The references are supplied in a file under ./debian and
        installed in a common location (via debhelper or other methods)
             1. in an already widely-used bibliographic format
             2. in a RFC822 format that is converted to other formats on
                installation

To me, only 4) is an option, and I prefer to go the 4.1 route. I guess
I'm familiar with debhelper enough that I could write an install script
that will be accepted into debhelper. But not before we have consesus
about that, of course. ;)

Another issues that comes to my mind is whether we want to provide
references to/about the software/package or information which
publication the authors want to be cited with (if there are several).
Maybe we should differ between citation (what to cite, important for
authors) and references (information, important for users of a
software). Thoughts?

Sorry for the long mail! The stuff went straight from my brain to my
fingers and might therefore be horryibly broken. ;)

Best regards
Manuel

[Charles Plessy-12]

Le Fri, Oct 10, 2008 at 01:24:22PM +0200, Manuel Prinz a écrit :
> The solution proposed by Andreas here is IMHO the way to go: Provide the
> information in the source package and install them where it is needed or
> wanted. This is i.e. one way the Emdebian project slims it's packages:
> Not calling certain debhelper scripts.

> Another issues that comes to my mind is whether we want to provide
> references to/about the software/package or information which
> publication the authors want to be cited with (if there are several).
> Maybe we should differ between citation (what to cite, important for
> authors) and references (information, important for users of a
> software). Thoughts?

Hi Manuel,

Thanks a lot for the summary !

It seems that if we go the Debhelper way, we could make dh_references
not install anything if DEB_BUILD_OPTIONS contains a 'nodoc' flag. When
a large majority of the scientific packages would contain
debian/references, we could enhance dh_references to maintain central
bibliographies in mainstream formats using DPKG triggers. It should
probably be possible to add comments such as "Cite this article if you
use 'foo'" in the references. With this proper documentation, we could
add the other references that the programs documentations cite.

I created a wiki page to organise our work when the brainstorming phase
will be over. http://wiki.debian.org/DebianScience/References . By the
way, I would be very interested to read the opinion of Michael, who
started this thread.

Have a nice day,

--
Charles Plessy
Debian Med packaging team,
Tsurumi, Kanagawa, Japan


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Michael Banck]

On Wed, Oct 08, 2008 at 09:27:13AM +0900, Charles Plessy wrote:
> You propose an additional control field for after Lenny release, but my
> gut feeling is that there will be a strong opposition on
> debian-devel@..., as extra fields make some files such as Packages.gz
> heavier, which is a disadvantage for platforms with limited CPU power,
> that have to parse this file despite not being likely to use this
> feature.

This is only the case if you add a XB-* field, which end up in the
binary package.  XS-* fields end up in the .dsc of the source package,
and X-* field do not end up in either.

It is the latter which I proposed initially, i.e. have the meta-data in
the debian/control of the package, but do not expose it to the .dsc or
.deb packages.

If that might be too hard to parse for web-frontends or users, we could
also just add it to the source package, that should not be an issue for
bandwidth or CPU cycles.  We could then ask packages.d.o or
packages.qa.d.o to expose that info as well, maybe.


Michael


--
To UNSUBSCRIBE, email to debian-science-request@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...