[svn-upgrade] Integrating new upstream version, jabref (2.5~beta1)
[debian/jabref.git] / src / help / XMPHelp.html
1 <html xmlns="http://www.w3.org/1999/xhtml">
2
3 <body text="#275856">
4     <basefont size="4" color="#2F4958" face="arial" />
5
6     <h1>XMP metadata support in JabRef</h1>
7
8     <p>XMP is a standard created by Adobe Systems for storing
9     metadata (data about data) in files. An well known example for
10     metadata are MP3 tags, which can be used to describe artist,
11     album and song name of a MP3 file. Adding metadata to MP3 helps
12     other people to identify the songs correctly independent of
13     file-name and can provide means for software (MP3 players for
14     instance) to sort and group songs.</p>
15
16     <p>With XMP-support the JabRef team tries to bring the
17     advantages of metadata to the world of reference managers. You
18     can now choose to "Write XMP" metadata in the General Tab of
19     JabRef, which will put all the Bibtex information into the PDF.
20     If you then email this PDF to a collegue she can just drag the
21     file into JabRef and all information that you entered will be
22     available to her.</p>
23
24     <h2>Usage</h2>
25
26     <p>To use the XMP-feature in JabRef you can do the
27     following:</p>
28
29     <ul>
30         <li>To <b>import a single annotated PDF-file</b> that
31         contains XMP you can select "File -&gt; Import into...
32         -&gt; XMP-annotated PDF" or drag the file into the main
33         view.</li>
34
35         <li>To <b>write the bibliographic information to the
36         associated PDF</b> do the following: Double click the entry
37         in the main view, go to the "General" tab and click on
38         "Write XMP".</li>
39
40         <li>If you want <b>to annotate all the PDFs in a given
41         database</b> you can select "Tools -&gt; Write XMP for
42         database"</li>
43
44         <li>To verify if it worked you can open the PDF in Adobe
45         Acrobat and select "File -&gt; Document Properties -&gt;
46         Additional Metadata -&gt; Advanced". In the tree to the
47         right you should see an entry called
48         "http://purl.org/net/bibteXMP". This works only with Adobe
49         Acrobat, not with Adobe Reader.</li>
50
51         <li>If you don't have Adobe Acrobat, you can use
52         <i>pdfinfo</i> instead in order to see the XMP metadata.
53         <i>pdfinfo</i> is part of Xpdf
54         (<code>www.foolabs.com/xpdf</code>) and Poppler
55         (<code>http://poppler.freedesktop.org</code>).</li>
56
57         <li style="list-style: none">
58             <div style="margin-left: 2em">
59                 <h2>BibteXmp Fileformat</h2>
60
61                 <p>XMP uses a subset of the Resource Description
62                 Framework (RDF) to store data. For JabRef a new
63                 metadata format is used which maps very closely to
64                 BibTeX. Basically all fields and values are turned
65                 into nodes of an XML document. Only authors and
66                 editors are stored as rdf:Seq-structures, so users
67                 of the data can skip the splitting on 'and's. All
68                 strings and crossrefs will be resolved in the
69                 data.</p>
70
71                 <p>The following easy minimal schema is used:</p>
72
73                 <ul>
74                     <li>The BibTeX-key is stored as
75                     <code>bibtexkey</code>.</li>
76
77                     <li>The type of the BibTeX-entry is stored as
78                     <code>entrytype</code>.</li>
79
80                     <li><code>author</code> and <code>editor</code>
81                     are encoding as <code>rdf:Seq</code>s where the
82                     individual authors are represented as
83                     <code>rdf:li</code>s.</li>
84
85                     <li>All other fields are saved using their
86                     field-name as is.</li>
87                 </ul><br />
88                 <br />
89
90
91                 <p>The following is an example of the mapping</p>
92                 <pre>
93 @INPROCEEDINGS{CroAnnHow05,
94   author = {Crowston, K. and Annabi, H. and Howison, J. and Masango, C.},
95   title = {Effective work practices for floss development: A model and propositions},
96   booktitle = {Hawaii International Conference On System Sciences (HICSS)},
97   year = {2005},
98   owner = {oezbek},
99   timestamp = {2006.05.29},
100   url = {http://james.howison.name/publications.html}
101 }
102 </pre>will be transformed into
103                 <pre>
104 &lt;rdf:Description xmlns:bibtex="http://jabref.sourceforge.net/bibteXMP/"
105     bibtex:bibtexkey="CroAnnHow05"
106     bibtex:year="2005"
107     bibtex:title="Effective work practices for floss development: A model and propositions"
108     bibtex:owner="oezbek"
109     bibtex:url="http://james.howison.name/publications.html"
110     bibtex:booktitle="Hawaii International Conference On System Sciences (HICSS)"
111     bibtex:timestamp="2006.05.29"&gt;
112         &lt;bibtex:author&gt;
113             &lt;rdf:Seq&gt;
114                 &lt;rdf:li&gt;K. Crowston&lt;/rdf:li&gt;
115                 &lt;rdf:li&gt;H. Annabi&lt;/rdf:li&gt;
116                 &lt;rdf:li&gt;J. Howison&lt;/rdf:li&gt;
117                 &lt;rdf:li&gt;C. Masango&lt;/rdf:li&gt;
118             &lt;/rdf:Seq&gt;
119         &lt;/bibtex:author&gt;
120     &lt;bibtex:entrytype&gt;Inproceedings&lt;/bibtex:entrytype&gt;
121 &lt;/rdf:Description&gt;
122 </pre>
123
124                 <p>Beware of the following caveats if you trying to
125                 parse bibteXMP:</p>
126
127                 <ul>
128                     <li>In RDF attribute-value pairs can also be
129                     expressed as nodes and vice versa.</li>
130                 </ul><br />
131                 <br />
132
133
134                 <h2>Related Links:</h2>
135
136                 <p>Some links about XMP and annotating PDFs:</p>
137
138                 <ul>
139                     <li>
140                     <a href="http://freelancepropaganda.com/themp/">
141                     James Howison's blog "Themp---Managing Academic
142                     Papers like MP3s"</a></li>
143
144                     <li>
145                     <a href="http://www.xml.com/pub/a/2004/09/22/xmp.html">
146                     XML.com article about XMP</a></li>
147
148                     <li><a href="http://jempbox.org">JempBox</a>
149                     and <a href="http://pdfbox.org">PDFBox</a> by
150                     Ben Litchfield are the Jaba libraries used to
151                     access the PDFs and the metadata stream.</li>
152
153                     <li>
154                     <a href="http://episteme.arstechnica.com/eve/ubb.x/a/tpc/f/8300945231/m/377001889631">
155                     Good thread on ArsTechnica discussing the
156                     management of PDFs.</a></li>
157
158                     <li>
159                     <a href="http://www.adobe.com/devnet/xmp/pdfs/xmp_specification.pdf">
160                     Adobe XMP Specification</a></li>
161                 </ul><br />
162                 <br />
163
164             </div>
165         </li>
166     </ul>
167 </body>
168 </html>