Imported Upstream version 2.9.1+ds
[debian/jabref.git] / src / help / ExternalFiles.html
1 <html xmlns="http://www.w3.org/1999/xhtml">\r
2 <head>\r
3 <link rel="stylesheet" type="text/css" href="jabref_help.css"/>\r
4 </head>\r
5 \r
6 <body>\r
7 \r
8     <h1>PDF/PS/URL/DOI links in JabRef</h1>\r
9 \r
10     <p><b>Note:</b> JabRef 2.3\r
11     and later versions offer an <a href="FileLinks.html">improved\r
12     system for external file links</a>.</p>\r
13 \r
14     <p>JabRef lets you link up your entries with PDF or PS files\r
15     stored on your system, as well as links to the document on the\r
16     web in the form of an URL or a DOI identifier.</p>\r
17 \r
18     <h2>Setting up external viewers</h2>\r
19 \r
20     <p>The program has to know\r
21     which external viewers to use for PDF, PS and web pages. These\r
22     are by default set to values that probably make sense for your\r
23     operating system, so there's a fair chance you don't have to\r
24     change these values.</p>\r
25 \r
26     <p>To change the external viewer settings, go to <b>Options\r
27     -&gt; Preferences -&gt; External programs</b>.</p>\r
28 \r
29     <h2>Opening external files or links</h2>\r
30 \r
31     <p>There are several ways\r
32     to open an external file or web page. In the entry editor, you\r
33     can double click on the text field containing the file name,\r
34     DOI or URL. In the entry table you can select an entry and use\r
35     the menu choice, keyboard shortcut or the right-click menu to\r
36     open the file or web page. Finally, you can click on a PDF, PS,\r
37     URL or DOI icon.</p>\r
38 \r
39     <p>By default the entry table will contain two columns with\r
40     icons for those entries that link to external files and URLs.\r
41     You can disable any of these in <b>Preferences -&gt; Table</b>.\r
42     The second column of the entry table shows icons for PDF or PS\r
43     files (only PDF if both are present), and the third column\r
44     shows icons for URL or DOI (only URL if both are present). You\r
45     open the file or web page by clicking on an icon.</p>\r
46 \r
47     <p><b>Note:</b> If the PS field does not appear in the entry\r
48     editor (in the 'General' panel), you may have to\r
49     <a href="GeneralFields.html">customize the entry types of the\r
50     general fields</a>.</p>\r
51 \r
52     <h2>The main PDF and PS directories</h2>\r
53 \r
54     <p>JabRef makes it easy to\r
55     link PDF and PS files to your entries. To take advantage of\r
56     this, you have to indicate in <b>Options -&gt; Preferences\r
57     -&gt; External programs</b> your main PDF and PS directories.\r
58     All PDF and PS files that are stored in or below each of these\r
59     directories will be referred to with a relative path by JabRef,\r
60     making it easy for you if you need to move the PDF and PS\r
61     directories, or if several users use the same database from\r
62     different network places.</p>\r
63 \r
64     <p>Additionally, if you give your PDF and PS files names that\r
65     correspond to the relevant entry's bibtex key (plus '.pdf' or\r
66     '.ps'), JabRef will be able to search your main directories and\r
67     its subfolders for the correct PDF and PS. Once the\r
68     correctly-named PDF or PS is in place you access this function\r
69     by clicking the 'Auto' button next to the PDF and PS fields in\r
70     the entry editor. If the PDF or PS is found, the field will\r
71     immediately be set.</p>\r
72 \r
73     <p>If you name a PDF or PS file as mentioned, you can also open\r
74     the file without setting the PDF or PS field of the entry at\r
75     all. The downside is that the PDF or PS icon will not appear in\r
76     the table unless you do (manually or with the 'Auto'\r
77     button).</p>\r
78 \r
79     <h2>The database-specific PDF and PS directories</h2>\r
80 \r
81     <p>You can set PDF and PS directories specific to a database\r
82     (<b>File -&gt; Database properties</b>). These directories will\r
83     supersede the main directories.</p>\r
84 \r
85     <h2><a name="RegularExpressionSearch"\r
86        id="RegularExpressionSearch">Using Regular Expression Search\r
87        for Auto-Linking</a></h2>\r
88 \r
89     <p>In the previous sections JabRef's auto-linking feature was\r
90     described: If you choose names for your files corresponding to\r
91     the bibtex-key + plus the extension, JabRef will automatically\r
92     be able to find it.</p>\r
93 \r
94     <p>Since JabRef 2.2 it is now possible to have greater\r
95     flexibility in the naming scheme by using regular expression\r
96     for the search. In most cases it should not be necessary though\r
97     to adapt the given default.</p>\r
98 \r
99     <p>If you open the external preferences (Options -&gt;\r
100     Preferences -&gt; External Programs) you will find an option\r
101     called "Use Regular Expression Search". Checking this option\r
102     will allow you to enter your own regular expression for search\r
103     in the PDF directories.</p>\r
104 \r
105     <p>The following syntax is understood:</p>\r
106 \r
107     <ul>\r
108         <li><code>*</code> - Search in all immediate all\r
109         subdirectories excluding the current and any deeper\r
110         subdirectories.</li>\r
111 \r
112         <li><code>**</code> - Search in all subdirectories\r
113         recursively AND the current directory.</li>\r
114 \r
115         <li><code>.</code> and <code>..</code> - The current\r
116         directory and the parent directory.</li>\r
117 \r
118         <li><code>[title]</code> - All expressions in square\r
119         brackets are replace by the corresponding field in the\r
120         current entry</li>\r
121 \r
122         <li><code>[extension]</code> - Is replaced by the\r
123         file-extension of the field you are using.</li>\r
124 \r
125         <li>All other text is interpreted as a regular expression.\r
126         But caution: You need to escape backslashes by putting two\r
127         backslashes after each other to not confuse them with the\r
128         path-separator.</li>\r
129     </ul>\r
130 \r
131     <p>The default for searches is\r
132     <code>**/.*[bibtexkey].*\\.[extension]</code>. As you can see\r
133     this will search in all subdirectories of the extension-based\r
134     directory (for instance in the PDF directory) for any file that\r
135     has the correct extension and contains the Bibtex-key\r
136     somewhere.</p>\r
137 </body>\r
138 </html>\r