bibdocfile: treatment of comments and descriptions

[tiborsimko]

Originally on 2011-05-17

Consider setting a document file comment and description like this:

sudo -u www-data /opt/invenio/bin/bibdocfile --recid 98 --docid 87 --set-comment='This is comment' --set-description='This is description' --yes-i-know

This creates the following MARC:

$$uhttp://localhost/record/98/files/9709037.pdf$$yThis is description$$zThis is comment

and the following Files tab display:

version 1
9709037.pdf     [1.05 MB] 16 May 2011, 14:28    This is description

The problem here is that (i) the comment information is not printed anywhere in the Files tab, it exists only in MARC; (ii) the BibUpload Admin Guide example on FFT $c $d brings forward an example according to which people would be putting up verbose comments into the description subfield instead.

We should harmonise the behaviour of file comments vs descriptions, document the two in the FFT guide, provide coherent usage example in the FFT guide, and modify the Files tab display accordingly.

[kaplun]

Originally on 2011-05-17

Hi Tibor,

originally the description was supposed to be the visible string, clickable by the final user (i.e. sort of the body of the <a> tag), while comment should contain anything else that is important to keep track off but that should not be automatically disclosed to the final user.

In the comment one could have put any blob in principle.

Now technical information can be encoded in the subformat string, so that the comment can be indeed used only for human oriented information.

It makes perfect sense to display the comment in the /files tab.

[tiborsimko]

Originally on 2011-05-17

Replying to [comment:1 skaplun]:

originally the description was supposed to be the visible string, clickable by the final user (i.e. sort of the body of the <a> tag)

Yes, it was indeed -- but this was not coherent with the FFT guide example that said:

    <record>
        <controlfield tag="001">123</controlfield>
        <datafield tag="FFT" ind1=" " ind2=" ">
            <subfield code="a">/tmp/thesis.pdf</subfield>
            <subfield code="t">Main</subfield>
            <subfield code="d">
              This is the fulltext version of my thesis in the PDF format.
              Chapter 5 still needs some revision.
            </subfield>
        </datafield>
    </record>

Hence this ticket to clean these label-vs-description-vs-comments issues, y-z-c-d subfields, and what-is-stored vs what-is-displayed questions...

[tiborsimko]

Originally on 2011-05-17

Replying to [comment:1 skaplun]:

In the comment one could have put any blob in principle.

BTW, this would not be so good, since comment is mapped onto MARC field 8564 $z...

[kaplun]

Originally on 2013-02-01

The attached patch implement this for maint-1.0

[kaplun]

Originally on 2013-02-01

And this is for maint-1.1

[tiborsimko]

I had a look at the old maint-1.0 related patch:

From e9b59bd51d056c589648d17e81f592d9891769f4 Mon Sep 17 00:00:00 2001
From: Samuele Kaplun <samuele.kaplun@cern.ch>
Date: Fri, 1 Feb 2013 15:25:10 +0100
Subject: [PATCH] BibDocFile: treatment of comments and descriptions

* Harmonises the behaviour of file comments vs descriptions by
  better documenting the two in the FFT guide, providing coherent
  usage example in the FFT guide, and modifying the Files tab
  display accordingly.
  (closes #635)
---
 .../bibupload/doc/admin/bibupload-admin-guide.webdoc |   18 ++++++++++++++----
 modules/websubmit/lib/bibdocfile.py                  |    3 ++-
 modules/websubmit/lib/websubmit_templates.py         |    9 +++++++--
 3 files changed, 23 insertions(+), 7 deletions(-)

and concerning the following bit:

-    def tmpl_bibdocfile_filelist(self, ln, recid, name, version, md, superformat, subformat, nice_size, description):
+    def tmpl_bibdocfile_filelist(self, ln, recid, name, version, md, superformat, subformat, nice_size, description, comment):

I wonder whether we should leave this out from maint-1.0 and maint-1.1 branches, because it would change the template API and the output behaviour, which may be annoying to some sites if they relied on the old behaviour.

IOW, we may want to commit only documentation related parts to maint branches, keeping the display amending part only for master. @kaplun OK with you? If yes, I'll amend your patches in this respect, and merge.

[kaplun]

@tiborsimko sure, perfectly fine with me...

[tiborsimko]

OK, I'll merge it that way. BTW this was supposed to go to maint-1.0 and above: any particular reason why you changed the branch and milestones?

[kaplun]

mmh... probably I was drunk? (I ate Indian food for lunch)

[tiborsimko]

OK, fixed :smile: