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