Re: tasks overview wishlist: Canonical citing reference
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@l.d.o, 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
Reply to: