tellico/doc/en/advanced.docbook

<chapter id="advanced">
<title>Advanced Usage</title>

<sect1 id="command-line">
<title>Command Line Options</title>

<para>
When running &appname; from the command line, there are several options for opening data files. They may be seen by running <userinput>tellico --help</userinput>.
</para>

<programlisting>
Usage: tellico [Qt-options] [KDE-options] [options] [filename]

Tellico - a collection manager for KDE

Options:
  --nofile                  Do not reopen the last open file
  --bibtex                  Import &lt;filename&gt; as a bibtex file
  --mods                    Import &lt;filename&gt; as a MODS file
  --ris                     Import &lt;filename&gt; as a RIS file

Arguments:
  filename                  File to open
</programlisting>

</sect1>

<sect1 id="dcop-interface">
<title>&DCOP; Interface</title>

<para>
&appname; has a minimal &DCOP; interface, which can be used for scripting or interacting with a running application from the command-line. As with all &DCOP; calls, you need to specify the application you want to interface with, and the particular interface. The name of the &DCOP; application is <constant>tellico-&lt;pid&gt;</constant>, where <emphasis>&lt;pid&gt;</emphasis> is the process id of the running application.
</para>

<sect2 id="dcop-commands">
<title>DCOP Commands</title>

<para>Two &DCOP; objects are available in the tellico interface: <constant>tellico</constant> and <constant>collection</constant>.</para>

<sect3 id="dcop-tellico">
<title>The <constant>tellico</constant> Object</title>

<para>The full list of &DCOP; commands in the <constant>tellico</constant> object is shown below:</para>

<programlisting>
bool importTellico(TQString file, TQString action)
bool importBibtex(TQString file, TQString action)
bool importMODS(TQString file, TQString action)
bool importRIS(TQString file, TQString action)
bool exportXML(TQString file)
bool exportZip(TQString file)
bool exportBibtex(TQString file)
bool exportHTML(TQString file)
bool exportCSV(TQString file)
bool exportPilotDB(TQString file)
QValueList&lt;long int&gt; selectedEntries()
QValueList&lt;long int&gt; filteredEntries()
void openFile(TQString file)
void setFilter(TQString text)
bool showEntry(long int id)
</programlisting>

<para>
For the four import commands, the first argument is the file to import, and the second is the import action. Three actions are available: <emphasis>replace</emphasis>, <emphasis>append</emphasis>, and <emphasis>merge</emphasis>. Four file formats are supported for importing: Tellico XML files, Bibtex files, MODS files, and RIS files.
</para>

<para>
The current open collection in &appname; may be exported to a file, in either Tellico XML format, Tellico ZIP format, Bibtex, HTML, comma-separated values (CSV), or the PilotDB format.
</para>

<para>A list of the entry IDs currently selected or being filtered is able to facilitate showing or updating entries in the view.</para>

<para> A new data file may be opened by using the <command>openFile()</command> command. The full path must be specified.</para>

<para>A new filter may be set using the <command>setFilter()</command> command, which is the equivalent of typing in the filter box in the main window.</para>

<para>Given an entry ID, <command>showEntry()</command> will select that entry and show the entry details in the main window.</para>
</sect3>

<sect3 id="dcop-collection">
<title>The <constant>collection</constant> Object</title>

<para>The full list of &DCOP; commands in the <constant>collection</constant> object is shown below:</para>

<programlisting>
long int addEntry()
bool removeEntry(long int entryID)
QStringList values(TQString fieldName)
QStringList values(long int entryID,TQString fieldName)
QStringList bibtexKeys()
TQString bibtexKey(long int entryID)
bool setFieldValue(long int entryID,TQString fieldName,TQString value)
bool addFieldValue(long int entryID,TQString fieldName,TQString value)
</programlisting>

<para>
A new empty entry may be created in the current collection using the <command>addEntry()</command> command. The return value is the entry ID, which can then be used to set the field values in the entry. An entry can be deleted from the collection by calling <command>removeEntry()</command>.
</para>

<para>
Calling <command>values()</command> using just a field name will return all the values for that field for the currently selected entries. If no entries are selected, the return list is empty. If an entry ID is included in the command, the field values for that specific entry are returned.
</para>

<para>
If the current collection is a bibliography, calling <command>bibtexKeys()</command> will return the Bibtex citation key for all selected entries. The bibtexKey for a specific entry may be found by using the <command>bibtekKey()</command> command.
</para>

<para>
Entries can be edited directly with the &DCOP; interface. Given an entry ID, <command>setFieldValue()</command> will set the field value directly. To add a value, without affecting the existing values, use <command>addFieldValue()</command>. The new value gets appended to the end of the existing list.
</para>
</sect3>

</sect2>

<sect2 id="dcop-examples">
<title>DCOP Examples</title>

<para>
Here are some examples for scripting &appname; using the &DCOP; interface. Since the <emphasis>pid</emphasis> must be known, the easiest way to include that in the shell command is like so: <userinput>dcop $(dcop | grep tellico) tellico</userinput>.
</para>

<screen width="40">
<emphasis>Open a Bibtex file</emphasis>
<prompt>%</prompt> <userinput>dcop $(dcop | grep tellico) tellico importBibtex ~/documents/reference.bib replace</userinput>
<computeroutput>true</computeroutput>
</screen>

<screen width="40">
<emphasis>Export a Bibtex file</emphasis>
<prompt>%</prompt> <userinput>dcop $(dcop | grep tellico) tellico exportBibtex ~/documents/reference.bib</userinput>
<computeroutput>true</computeroutput>
</screen>

<screen width="40">
<emphasis>Echo the citation key of the current selection</emphasis>
<prompt>%</prompt> <userinput>dcop $(dcop | grep tellico) collection bibtexKeys</userinput>
<computeroutput>stephenson2004</computeroutput>
</screen>

<screen width="40">
<emphasis>Add a new entry and set the title</emphasis>
<prompt>%</prompt> <userinput>myid=`dcop $(dcop | grep tellico) collection addEntry`</userinput>
<prompt>%</prompt> <userinput>dcop $(dcop | grep tellico) collection setFieldValue $myid title "My New Book"</userinput>
<computeroutput>true</computeroutput>
</screen>

</sect2>

</sect1>

</chapter>