[pybliographer] rearrange documentation
- From: Zoltan Kota <zkota src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [pybliographer] rearrange documentation
- Date: Mon, 23 Aug 2010 22:29:46 +0000 (UTC)
commit e226e20149fb78acb641dd99f8efe27fd4713231
Author: Zoltan Kota <zoltank gmail com>
Date: Tue Aug 24 00:27:44 2010 +0200
rearrange documentation
Makefile.am | 2 +-
configure.ac | 4 +-
doc/C/authors.xml | 82 --
doc/C/commandline.xml | 61 --
doc/C/config.xml | 56 --
doc/C/gui.xml | 582 --------------
doc/C/preface.xml | 114 ---
doc/C/pybliographer.xml | 170 ----
doc/C/script.xml | 265 -------
doc/C/start.xml | 68 --
doc/C/styles.xml | 136 ----
doc/it/Makefile.am | 52 --
doc/it/config.sgml | 74 --
doc/it/database.sgml | 195 -----
doc/it/edit.png | Bin 18386 -> 0 bytes
doc/it/entry.sgml | 124 ---
doc/it/fields.png | Bin 15467 -> 0 bytes
doc/it/format.png | Bin 11212 -> 0 bytes
doc/it/gui.sgml | 351 ---------
doc/it/iterator.sgml | 94 ---
doc/it/key.sgml | 66 --
doc/it/main.png | Bin 37748 -> 0 bytes
doc/it/medline.png | Bin 18827 -> 0 bytes
doc/it/open.png | Bin 13575 -> 0 bytes
doc/it/pyblio.sgml | 105 ---
doc/it/script.sgml | 206 -----
doc/it/search.png | Bin 21885 -> 0 bytes
doc/it/selection.sgml | 89 ---
doc/it/sort.png | Bin 10075 -> 0 bytes
doc/it/sort.sgml | 45 --
doc/it/styles.sgml | 152 ----
doc/it/tester.sgml | 45 --
doc/it/topic.dat | 1 -
doc/it/url.sgml | 59 --
{doc => help}/C/Makefile.am | 5 +-
{doc => help}/C/figures/edit.png | Bin 20728 -> 20728 bytes
{doc => help}/C/figures/edit2.png | Bin 42281 -> 42281 bytes
{doc => help}/C/figures/fields.png | Bin 15467 -> 15467 bytes
{doc => help}/C/figures/format.png | Bin 11212 -> 11212 bytes
{doc => help}/C/figures/main.png | Bin 84624 -> 84624 bytes
{doc => help}/C/figures/medline.png | Bin 18827 -> 18827 bytes
{doc => help}/C/figures/open.png | Bin 41476 -> 41476 bytes
{doc => help}/C/figures/search.png | Bin 47735 -> 47735 bytes
{doc => help}/C/figures/sort.png | Bin 10075 -> 10075 bytes
{doc => help}/C/legal.xml | 0
{doc => help}/C/pybliographer-C.omf | 4 +-
help/C/pybliographer.xml | 1488 +++++++++++++++++++++++++++++++++++
{doc => help}/Makefile.am | 0
48 files changed, 1494 insertions(+), 3201 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index 170bf87..a49fe97 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -28,7 +28,7 @@ SUBDIRS = Pyblio \
tests \
Styles \
po \
- doc
+ help
appicondir = $(datadir)/pixmaps
diff --git a/configure.ac b/configure.ac
index 7c1b92b..d33815d 100644
--- a/configure.ac
+++ b/configure.ac
@@ -89,8 +89,8 @@ AC_CONFIG_FILES(
Pyblio/Output/Makefile
Pyblio/ConfDir/Makefile
Pyblio/Style/Makefile
- doc/Makefile
- doc/C/Makefile
+ help/Makefile
+ help/C/Makefile
Styles/Makefile
)
diff --git a/doc/C/Makefile.am b/help/C/Makefile.am
similarity index 88%
rename from doc/C/Makefile.am
rename to help/C/Makefile.am
index f47ca81..af2bbd3 100644
--- a/doc/C/Makefile.am
+++ b/help/C/Makefile.am
@@ -24,10 +24,7 @@ docname = pybliographer
lang = C
omffile = pybliographer-C.omf
-entities = \
- legal.xml authors.xml commandline.xml \
- config.xml gui.xml preface.xml \
- script.xml start.xml styles.xml
+entities = legal.xml
include $(top_srcdir)/xmldocs.make
diff --git a/doc/C/figures/edit.png b/help/C/figures/edit.png
similarity index 100%
rename from doc/C/figures/edit.png
rename to help/C/figures/edit.png
diff --git a/doc/C/figures/edit2.png b/help/C/figures/edit2.png
similarity index 100%
rename from doc/C/figures/edit2.png
rename to help/C/figures/edit2.png
diff --git a/doc/C/figures/fields.png b/help/C/figures/fields.png
similarity index 100%
rename from doc/C/figures/fields.png
rename to help/C/figures/fields.png
diff --git a/doc/C/figures/format.png b/help/C/figures/format.png
similarity index 100%
rename from doc/C/figures/format.png
rename to help/C/figures/format.png
diff --git a/doc/C/figures/main.png b/help/C/figures/main.png
similarity index 100%
rename from doc/C/figures/main.png
rename to help/C/figures/main.png
diff --git a/doc/C/figures/medline.png b/help/C/figures/medline.png
similarity index 100%
rename from doc/C/figures/medline.png
rename to help/C/figures/medline.png
diff --git a/doc/C/figures/open.png b/help/C/figures/open.png
similarity index 100%
rename from doc/C/figures/open.png
rename to help/C/figures/open.png
diff --git a/doc/C/figures/search.png b/help/C/figures/search.png
similarity index 100%
rename from doc/C/figures/search.png
rename to help/C/figures/search.png
diff --git a/doc/C/figures/sort.png b/help/C/figures/sort.png
similarity index 100%
rename from doc/C/figures/sort.png
rename to help/C/figures/sort.png
diff --git a/doc/C/legal.xml b/help/C/legal.xml
similarity index 100%
rename from doc/C/legal.xml
rename to help/C/legal.xml
diff --git a/doc/C/pybliographer-C.omf b/help/C/pybliographer-C.omf
similarity index 89%
rename from doc/C/pybliographer-C.omf
rename to help/C/pybliographer-C.omf
index 9104a5a..b6e69da 100644
--- a/doc/C/pybliographer-C.omf
+++ b/help/C/pybliographer-C.omf
@@ -12,9 +12,9 @@
Pybliographer Manual
</title>
<date>
- 2008-10-07
+ 2010-08-24
</date>
- <version identifier="2.6" date="2008-10-07" description="Updated for Pybliographer 1.2.12"/>
+ <version identifier="2.7" date="2010-08-24" description="Updated for Pybliographer 1.2.14"/>
<subject category="GNOME|Applications|Office"/>
<description>
User manual for the Pybliographer application.
diff --git a/help/C/pybliographer.xml b/help/C/pybliographer.xml
new file mode 100644
index 0000000..c268fab
--- /dev/null
+++ b/help/C/pybliographer.xml
@@ -0,0 +1,1488 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
+
+<!ENTITY legal SYSTEM "legal.xml">
+
+<!ENTITY pyb "pybliographer">
+<!ENTITY pyc "pybliographic">
+<!ENTITY Pyc "Pybliographic">
+<!ENTITY appversion "1.2.14">
+<!ENTITY manrevision "2.7">
+<!ENTITY date "August 2010">
+<!ENTITY app "Pybliographer">
+]>
+
+<!-- =============Document Header ============================= -->
+<book id="index" lang="en">
+ <title>&app; Manual V&manrevision;</title>
+ <bookinfo>
+ <copyright>
+ <year>2003-2010</year>
+ <holder>Zoltán Kóta</holder>
+ </copyright>
+ <copyright>
+ <year>1999-2010</year>
+ <holder>Frédéric Gobry</holder>
+ </copyright>
+
+ &legal;
+
+ <authorgroup>
+ <author>
+ <firstname>Zoltán</firstname>
+ <surname>Kóta</surname>
+ </author>
+ <author>
+ <firstname>Frédéric</firstname>
+ <surname>Gobry</surname>
+ </author>
+
+ </authorgroup>
+
+ <revhistory>
+ <revision>
+ <revnumber>&app; Manual V&manrevision;</revnumber>
+ <date>&date;</date>
+ <revdescription>
+ <para role="author">Zoltán Kóta, Frédéric Gobry</para>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>&app; Manual V2.6</revnumber>
+ <date>October 2008</date>
+ <revdescription>
+ <para role="author">Zoltán Kóta, Frédéric Gobry</para>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>&app; Manual V2.5</revnumber>
+ <date>February 2005</date>
+ <revdescription>
+ <para role="author">Zoltán Kóta, Frédéric Gobry</para>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>&app; Manual V2.4</revnumber>
+ <date>November 2004</date>
+ <revdescription>
+ <para role="author">Zoltán Kóta, Frédéric Gobry</para>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>&app; Manual V2.3</revnumber>
+ <date>June 2004</date>
+ <revdescription>
+ <para role="author">Zoltán Kóta, Frédéric Gobry</para>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>&app; Manual V2.2</revnumber>
+ <date>March 2004</date>
+ <revdescription>
+ <para role="author">Zoltán Kóta, Frédéric Gobry</para>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>&app; Manual V2.1</revnumber>
+ <date>January 2004</date>
+ <revdescription>
+ <para role="author">Zoltán Kóta, Frédéric Gobry</para>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>&app; Documentation</revnumber>
+ <date>1999</date>
+ <revdescription>
+ <para role="author">Frédéric Gobry</para>
+ </revdescription>
+ </revision>
+ </revhistory>
+
+ <releaseinfo>This manual describes version &appversion; of &app;.
+ </releaseinfo>
+ <legalnotice>
+ <title>Feedback</title>
+ <para>To report a bug or make a suggestion regarding the &app;
+ application or this manual, follow the directions in the
+ <ulink type="http" url="http://www.pybliographer.org/Help";>
+ Pybliographer help page</ulink>.
+ </para>
+ </legalnotice>
+
+ <indexterm zone="index">
+ <primary>Pybliographer</primary>
+ </indexterm>
+ <indexterm zone="index">
+ <primary>pybliographer</primary>
+ </indexterm>
+ <indexterm zone="index">
+ <primary>pybliographic</primary>
+ </indexterm>
+ <indexterm zone="index">
+ <primary>bibliography manager</primary>
+ </indexterm>
+
+ </bookinfo>
+
+<!-- ============= Document Body ============================= -->
+
+
+<preface id="book-preface">
+ <title>Preface</title>
+ <sect1 id="typography">
+ <title>Typographical conventions</title>
+ <para>
+ In this book, we'll mark some words with special typography:
+ </para>
+ <itemizedlist mark='bullet'>
+ <listitem><para><application>Applications</application></para></listitem>
+ <listitem><para><command>Commands</command> you type at the command
+ line</para></listitem>
+ <listitem><para><filename>Filenames</filename></para></listitem>
+ <listitem><para><replaceable>Replaceable text</replaceable></para></listitem>
+ <listitem><para><guilabel>Labels</guilabel> for buttons and other
+ portions of the graphical interface</para></listitem>
+
+ <listitem><para> Menu selections look like this:
+ <menuchoice>
+ <guimenu>Menu</guimenu>
+ <guisubmenu>Submenu</guisubmenu>
+ <guimenuitem>Menu Item</guimenuitem>
+ </menuchoice>
+ </para></listitem>
+ <listitem><para><guibutton>Buttons</guibutton> you can
+ click</para></listitem>
+ <listitem><para><userinput>Anything you type
+ in</userinput></para></listitem>
+ </itemizedlist>
+
+ <para>
+ We'll provide assorted bits of additional information in tips
+ and notes as well.
+
+ <tip id="example-tip">
+ <title>Tip</title>
+ <para>
+ Tips and bits of extra information will look like
+ this.
+ </para>
+ </tip>
+
+ <note id="example-note">
+ <title>Note</title>
+ <para>
+ Notes will look like this.
+ </para>
+ </note>
+ </para>
+
+ <para>
+ We'll have warnings, in cases where you should be careful:
+
+ <warning id="example-warning">
+ <title>Example Warning</title>
+ <para>
+ This is what a warning looks like. If there's a chance
+ you'll run into trouble, we'll warn you beforehand.
+ </para>
+ </warning>
+ </para>
+ </sect1>
+
+
+ <sect1 id="other-help">
+ <title>Additional Help Sources</title>
+ <para>
+ For additional information, please, visit the &app; website at
+ <ulink type="http" url="http://pybliographer.org";>
+ http://pybliographer.org</ulink>. There is a mailing list also,
+ where you can get answers for your questions, you can report
+ bugs, etc.
+ </para>
+ </sect1>
+
+ <sect1 id="whats-new-in-one-two">
+ <title>What's New in &app; &appversion;</title>
+ <para>
+ You can find a list of bugs fixed and features added
+ in the <filename>News</filename> file supplied with the package.
+ See the source tarball of pybliographer, or the default doc directory
+ of your distribution (e.g. /usr/share/doc/pybliographer). You can
+ also browse the source code repository online.
+ </para>
+
+ </sect1>
+</preface>
+
+
+
+<chapter id="getting-started">
+ <title>Getting started with &app;</title>
+
+ <sect1 id="introduction">
+ <title>What is Pybliographer?</title>
+ <para>Pybliographer is a tool for working with bibliographic
+ databases. It provides a general framework that can be used to
+ manipulate these databases with a simple graphical interface,
+ but that can also be easily extended by the mean of a
+ scripting language, to fit a wide range of needs.</para>
+ </sect1>
+
+ <sect1 id="how-to-start">
+ <title>How to start Pybliographer?</title>
+ <para>You can start <application>&app;</application> in the
+ following ways:</para>
+ <variablelist>
+ <varlistentry>
+ <term>Graphical mode</term>
+ <listitem>
+ <para>To start <application>&app;</application> in
+ graphical mode from a command line, type the following
+ command, then press <keycap>Return</keycap>:</para>
+ <para>
+ <command>pybliographic</command>
+ </para>
+ <para>For information on the graphical interface, see
+ <xref linkend="graphical-interface" />.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Command line mode</term>
+ <listitem>
+ <para>You can start <application>&app;</application>
+ also in command line mode by typing the following
+ command followed by pressing <keycap>Return</keycap>:
+ </para>
+ <para>
+ <command>pybliographer</command>
+ </para>
+ <para>For information on the command line interface,
+ see <xref linkend="command-line" />.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>From the gnome menu</term>
+ <listitem>
+ <para>If the desktop file of the package is correctly
+ installed in your sytem, you can find a launcher under
+ the gnome menu to start the graphical interface of &app;.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>It is possible to set the PYBLIOGRAPHER_DATABASE environment variable to an
+ admissible bibliography file in order to open it always on startup, if no files are
+ specified on the command line. Example:</para>
+ <screen>
+ <prompt>bash$ </prompt><userinput>export PYBLIOGRAPHER_DATABASE=my/database.bib</userinput>
+ <prompt>bash$ </prompt><userinput>pybliographic</userinput>
+ </screen>
+ <para>It is equivalent to</para>
+ <screen>
+ <prompt>bash$ </prompt><userinput>pybliographic my/database.bib</userinput>
+ </screen>
+
+ </sect1>
+</chapter>
+
+
+
+<chapter id="graphical-interface">
+ <title>The graphical interface</title>
+
+ <para>The graphical user interface is called &pyc;. It provides a
+ simple access to the most common features of the underlying
+ engine, &pyb; and lets you search, sort and modify bibliographic
+ entries. Moreover, direct insertion of references into
+ <ulink type="http" url="http://www.lyx.org/";><application>Lyx
+ </application></ulink> and <ulink type="http"
+ url="http://kile.sourceforge.net/";><application>Kile</application>
+ </ulink>, direct queries on Medline, and
+ saving selected references in different formats are also possible.
+ </para>
+
+ <sect1 id="gui-creating">
+ <title>Creating a new database</title>
+
+ <para>When &pyc; is opened, you can immediately begin to create a
+ new database. The type of this database will be determined when
+ you will save it the first time.</para>
+
+ <para>To add a new entry, you can use the <menuchoice>
+ <guimenu>Edit</guimenu> <guimenuitem>Add</guimenuitem>
+ </menuchoice> menu, directly the <guibutton>Add</guibutton>
+ toolbar button or click with the right button in the list window
+ and select <guibutton>Add</guibutton>.
+ </para>
+
+ <para>You will find more information on the main window's usage in
+ <xref linkend="gui-navigate" />.</para>
+
+ </sect1>
+
+ <sect1 id="gui-opening">
+ <title>Opening a database</title>
+
+ <para>To open an existing database, click on the
+ <guibutton>Open</guibutton> toolbar button or go in the
+ <guimenu>File</guimenu> menu, and select <menuchoice>
+ <guimenu>File</guimenu> <guimenuitem>Open</guimenuitem>
+ </menuchoice>.</para>
+
+ <figure id="figopen">
+ <title>Opening a database</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/open.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows &app; open file window.</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+
+ <para>A file selection dialog will pop up (see <xref
+ linkend="figopen" />) and let you select a file. The type of the database
+ can also be selected. Opening an existing database, the type can be guessed if
+ you select <guibutton>- According to file suffix -</guibutton>.
+ </para>
+ <para>
+ It is also possible to open a file at a remote location (as well as a local file)
+ by typing the URI of the file (e.g. http://my.remote.site/pyblio.bib) using the
+ 'Open Location' dialog, which can be invoked by the <menuchoice><guimenu>File</guimenu>
+ <guimenuitem>Open Location</guimenuitem></menuchoice> menu item.
+ </para>
+ </sect1>
+
+ <sect1 id="gui-navigate">
+ <title>Navigating in the entries</title>
+
+ <para>Once you have opened a database, or started to create a new
+ one, the main window (see <xref linkend="figmain" />) displays a
+ list of all the entries on the top part of it. The fields
+ diplayed here can be configured under the <menuchoice><guimenu>
+ Settings</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>
+ menu item.</para>
+
+ <tip>
+ <para>It is possible to display two types of combined fields:
+ <emphasis>-author/editor</emphasis> and <emphasis>-author/title-</emphasis>.
+ </para>
+ </tip>
+
+ <para>Clicking on an entry displays its full content on the lower part of
+ the window. It is also possible to use the arrow keys to navigate in the
+ upper list.
+ </para>
+
+ <para>If an entry contains an <emphasis>URL</emphasis> field,
+ clicking on the small button next to the url, the appropriate
+ application is launched to view the target object
+ (e.g. PDF viewer for pdf files, web browser for http address).
+ See <xref linkend="gui-edit" /> about how to add an URL field to
+ an entry. Alternatively, you can open the URL with the help of the
+ <menuchoice><guimenu>View</guimenu><guisubmenu>Resource</guisubmenu>
+ </menuchoice> submenu item or the <menuchoice><guimenu>Resource</guimenu>
+ </menuchoice> pop up menu provided for the item list. If an item contains one or
+ more viewable fields (like url) containing viewable resources, it is marked with
+ an icon at the left edge of the item in the upper part of the main window (see
+ <xref linkend="figmain" />).
+ </para>
+
+ <tip>
+ <para>You can set the viewable fields and the applications used to view the resources
+ in the 'Resource' tab under the <menuchoice><guimenu>Settings</guimenu>
+ <guimenuitem>Preferences</guimenuitem></menuchoice> menu.
+ </para>
+ </tip>
+
+
+ <para>Clicking on an entry while pressing the
+ <keysym>Shift</keysym> key extends the selection to the clicked
+ entry. A click while pressing the <keysym>Control</keysym> key
+ toggles the entry without altering the state of the rest of the
+ selection. With copy and paste, or by drag and drop you can copy
+ one or more selected entries into a new window/database.</para>
+
+ <figure id="figmain">
+ <title>The main window</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/main.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows &app; main window.</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+
+ <para>Clicking the right button of the mouse in the list opens a
+ contextual menu. With this menu you can:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>add a new entry</para>
+ </listitem>
+ <listitem>
+ <para>edit the currently selected items</para>
+ </listitem>
+ <listitem>
+ <para>view the resource associated with the selected item</para>
+ </listitem>
+ <listitem>
+ <para>delete the currently selected items</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Note that some of these menu options can be disabled for a
+ given database or entry, provided that the corresponding action
+ can't be performed.</para>
+
+ <para>By clicking on the column titles of the list, you'll sort
+ the entries according to the corresponding field.</para>
+ </sect1>
+
+ <sect1 id="gui-searching">
+ <title>Searching</title>
+
+ <para>&Pyc; offers a quite powerful searching mechanism. For searching
+ you can use the quick search entry of the toolbar or the search dialog.
+ To open the search dialog, click on <menuchoice> <guimenu>Edit</guimenu>
+ <guimenuitem>Search</guimenuitem> </menuchoice> in the menu.
+
+ The dialog that appears (see <xref linkend="figsearch" />)
+ displays a search form at the top.</para>
+
+ <figure id="figsearch">
+ <title>The Search dialog</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/search.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows &app; search dialog.</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+
+ <sect2 id="gui-searching-simple">
+ <title>Simple searches</title>
+
+ <para>With a simple search, you can select the field that will
+ be searched and you can specify a regular expression to be
+ matched. <guibutton>- any field -</guibutton> means that all
+ the existing fields will be searched. This is usually more
+ time-consuming.</para>
+
+ </sect2>
+
+ <sect2 id="gui-searching-expert">
+ <title>Expert searches</title>
+
+ <para>An expert search is an expression that looks like:</para>
+
+ <programlisting>has('author','name') | -has('title','test')</programlisting>
+
+ <para> Such an expression means: select the entries where the
+ field <emphasis>author</emphasis> matches
+ <emphasis>name</emphasis>, or (symbol <symbol>|</symbol>)
+ where the field <emphasis>title</emphasis> does
+ <emphasis>not</emphasis> match <emphasis>test</emphasis>. The
+ boolean <symbol>and</symbol> is noted
+ <symbol>&</symbol>.</para>
+
+ <para>There are other commands available for this type of
+ search:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><command>has_key(<varname>keyname</varname>)</command>
+ searches on a key name.</para>
+ </listitem>
+ <listitem>
+ <para><command>has_type(<varname>typename</varname>)</command>
+ searches for entries of a given type name.</para>
+ </listitem>
+ <listitem>
+ <para><command>any_has(<varname>value</varname>)</command>
+ searches for the given value in all the fields of an
+ entry.</para>
+ </listitem>
+ <listitem>
+ <para><command>before(<varname>field</varname>,
+ <varname>year</varname>, <varname>month</varname>,
+ <varname>day</varname>)</command> searches for entries
+ where the specified date field is older than the
+ specified date.</para>
+ </listitem>
+ <listitem>
+ <para><command>after(<varname>field</varname>,
+ <varname>year</varname>, <varname>month</varname>,
+ <varname>day</varname>)</command>searches for entries
+ where the specified date field is younger than the
+ specified date.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="gui-searching-hierarchical">
+ <title>Hierarchical searches</title>
+
+ <para>After a search, only the selected items are displayed in
+ the main window. It makes it convenient to select a specific
+ author, and then browse its publications for example.</para>
+
+ <para> In addition, the results of all the searches are kept in
+ the tree located below the search form. Therefore, a new
+ search can be a refinement of a previous one. If you select
+ the tree item corresponding for example to all the articles
+ written by a certain Nostradamus, you'll be able to select
+ only those whose title contains the word eclipse.</para>
+
+ <para>Right-clicking in this tree pops up a contextual menu that
+ allows you to remove unuseful searches.</para>
+
+ <para>To select the full list of database entries again, just
+ click on the <emphasis>Full database</emphasis> item at the top
+ of the search tree, or push the 'Esc' button on the keyboard when
+ you are in the main window.</para>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="gui-sorting">
+ <title>Sorting</title>
+
+ <para>Clicking on the title of each column in the main index
+ provides some rudimentary way of sorting a database. A much
+ powerful method is to open the sort dialog (in <menuchoice>
+ <guimenu>Edit</guimenu> <guimenuitem>Sort</guimenuitem>
+ </menuchoice>). This menu, displayed in <xref linkend="figsort" />,
+ gives a list of fields which can be used as sort criterions, plus
+ a flag indicating how they are currently used. By clicking twice
+ on the item, it is possible to choose how the field will be used:
+ <itemizedlist>
+ <listitem>
+ <para>Nothing means the field is not in use.</para>
+ </listitem>
+ <listitem>
+ <para>A <symbol>triangle</symbol>-like symbol means sort in
+ <emphasis>ascending order</emphasis>.</para>
+ </listitem>
+ <listitem>
+ <para>An <symbol>upside down triangle</symbol>-like symbol
+ means sort in <emphasis>descending order</emphasis>.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>The order in which the sorting is performed depends on the
+ order in the list. To modify this order, simply drag and drop an
+ item to change its position. To make this sort order default, it
+ can be saved by clicking on the <guibutton>Set as default</guibutton>
+ button.</para>
+
+ <figure id="figsort">
+ <title>The Sort dialog</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/sort.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows &app; sort dialog.</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+
+ </sect1>
+
+ <sect1 id="gui-edit">
+ <title>Editing</title>
+
+ <sect2 id="gui-edit-basic">
+ <title>Basic editing</title>
+
+ <figure id="figedit">
+ <title>The Edition window</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/edit.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows &app; edition window.</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+
+ <para>The edition window is represented in <xref
+ linkend="figedit" />. On the right of each field, a symbol
+ indicates if &pyb; has been able to render all the information
+ given in that field. For example, a BibTeX field containing an
+ unknown command name cannot be correctly represented. In that
+ case, &pyb; provides a fake representation, and indicates it was
+ not able to do a good job on this field by setting a red symbol
+ on its right, instead of a green one.</para>
+ <warning>
+ <para>If you edit such an entry, you can loose the additional
+ information it contained. To avoid this, consider using native
+ editing (see <xref linkend="gui-edit-native" />).</para>
+ </warning>
+
+ <para>To edit the entries, simply type the corresponding text,
+ without any consideration for the database format being
+ used. For example, with <productname>BibTeX</productname>, don't
+ add any <symbol>{</symbol> or special characters to influence
+ the result, as they will be quoted by the system. For fields
+ requiring names (like author and editor), use the following
+ format: type one name per line, in the <emphasis>last name,
+ lineage, first name</emphasis> order. If an author or editor field
+ has too many names, you can end the list of names with <emphasis>
+ others</emphasis>; the standard bibtex styles convert this to
+ <emphasis>et al</emphasis>.</para>
+ <para>In addition to the standard fields, you can create your
+ own fields using the <guibutton>Create Field</guibutton> button.
+ </para>
+ <tip>
+ <para>You can customize the mandatory and optional fields for
+ the different type of entries. For example, associating the
+ <emphasis>URL</emphasis> field with a given type of entry, it is
+ possible to assign an url to an entry (e.g. the
+ location of the pdf version of an article or the address of a
+ website). See <xref linkend="figediturl" />. More information about
+ the association of fields can be found in
+ <xref linkend="gui-settings" />.</para>
+ </tip>
+
+ <figure id="figediturl">
+ <title>The Edition window - Optional fields</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/edit2.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows the optional fields containing URL.</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+
+ <para>The following keyboard shortcuts are available during
+ edition (in addition to the standard ones provided by
+ Gtk):</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <keycombo><keycap>Ctrl</keycap><keycap>TAB</keycap></keycombo>
+ to jump to the next field</para>
+ </listitem>
+ <listitem>
+ <para>
+ <keycombo><keycap>Shift</keycap><keycap>TAB</keycap></keycombo>
+ to jump to the previous field</para>
+ </listitem>
+ <listitem>
+ <para>
+ <keycombo><keycap>Ctrl</keycap><keycap>Enter</keycap></keycombo>
+ to accept the modifications</para>
+ </listitem>
+ <listitem>
+ <para><keycap>Esc</keycap> to cancel the edition</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>To specify a crossreference to another entry, just drag the
+ entry from the main list to the
+ <guilabel>Crossreference</guilabel> field. To remove a
+ crossreference, drag an empty selection on the field. To
+ unselect all the entries, you might need to use the
+ <keysym>Control</keysym> key, while clicking on the
+ entry.</para>
+ </sect2>
+
+ <sect2 id="gui-edit-native">
+ <title>Native editing</title>
+
+ <para>For databases like BibTeX that provide a specific syntax
+ (called <emphasis>native</emphasis> syntax), it is possible to
+ directly edit the entry in this format. Just click the button
+ called <guibutton>Native Editing</guibutton> at the bottom of
+ the window and type the entry in its native form.
+ </para>
+
+ <para>It is also possible to type native commands in the normal
+ editing window. For example, if you want to use special LaTeX
+ commands like <command>\textbf</command> in a title, you can
+ type them directly in the Title field by preceding the text
+ with a <symbol>@</symbol> symbol (as the first
+ character). After that symbol, you have to use all the BibTeX
+ conventions (braces, backslashes,...), as none of them will be
+ escaped or modified by &pyb;.</para>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="gui-lyx">
+ <title>Using &pyc; with <application>LyX</application></title>
+
+ <para>It is possible to directly use &pyb; in order to insert
+ bibliographic references into LyX. It is done through the LyX
+ <emphasis>server</emphasis>. The path of the LyX server pipe can
+ be defined in the <menuchoice><guimenu>Tools</guimenu>
+ <guimenuitem>Preferences</guimenuitem></menuchoice> dialog of LyX.
+ The same path should be given in &pyb;'s settings
+ (the default value is ~/.lyx/lyxpipe).</para>
+
+ <para>Then, in &pyc;, it is possible to select one or several
+ entries and insert their references into a running LyX simply by
+ clicking the <guibutton>Cite</guibutton> toolbar button, or
+ selecting the
+ <menuchoice><guimenu>Cite</guimenu>
+ <guimenuitem>Cite...</guimenuitem>
+ </menuchoice>
+ menu item.</para>
+
+ <para>For the moment, it is the user's job to ensure that he/she
+ inserts entries corresponding to the actual database being used.
+ &pyc; does not handle the full job of bibliography generation;
+ therefore it is necessary to use <command>bibtex</command> as
+ described in the LyX documentation.</para>
+ <note>
+ <para>&pyc; can interact with <application>Kile</application>
+ (>= 1.6) practically in the same way, since <application>Kile
+ </application> can also read <emphasis>lyx pipe</emphasis>.</para>
+ </note>
+ </sect1>
+
+ <sect1 id="gui-formats">
+ <title>Saving selected entries in different formats</title>
+
+ <para>Selected entries can be saved in different formats using
+ the <menuchoice><guimenu>Cite</guimenu> <guimenuitem>Format...
+ </guimenuitem></menuchoice> menu item (<xref linkend="figformat" />).
+ </para>
+
+ <figure id="figformat">
+ <title>Formatting entries</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/format.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows &app; formatting entries dialog.</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+
+
+ <para>As a result, a formatted output file is generated according
+ to a bibliographic style, either in HTML, LaTeX, Raw or Text format.
+ The &pyb; package contains some bibliographic styles, but own styles
+ can also be created easily. See also
+ <xref linkend="script-scripting-existing-pybformat" />.</para>
+ </sect1>
+
+ <sect1 id="gui-pubmed">
+ <title>Searching in PubMed</title>
+
+ <para>With &pyc;, it is possible to perform a Medline search. To
+ use this option, click on the <menuchoice><guimenu>File</guimenu>
+ <guimenuitem>Medline query...</guimenuitem></menuchoice> menu item. The
+ upcoming window is represented in <xref linkend="figmed" />.</para>
+
+ <figure id="figmed">
+ <title>Medline query</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/medline.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows &app; medline search dialog.</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+
+ <para>The keyword, you are looking for, should be written into the
+ <emphasis>Search PubMed for</emphasis> field. As it can be seen
+ in <xref linkend="figmed" />, a number of options (limitations) can
+ be set, which can help to obtain an optimal search result. The
+ matched references, resulted in by the query, appear in the main
+ window as a new database.</para>
+ </sect1>
+
+ <sect1 id="gui-settings">
+ <title>Configuration</title>
+
+ <para>Under the <menuchoice><guimenu>Settings</guimenu></menuchoice>
+ menu, you can find some options to customize &pyb;.</para>
+
+ <sect2 id="gui-settings-fields">
+ <title>Entry types and field names configuration</title>
+
+ <figure id="figfields">
+ <title>Configuration of fields and entry types</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/fields.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows &app; fields and entry types configuration
+ dialog.</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+
+ <para>Selecting the <menuchoice><guimenu>Settings</guimenu>
+ <guimenuitem>Fields</guimenuitem></menuchoice> menu item, it
+ is possible to add or remove fields, to set their type, and
+ to define which fields should be associated with a given type of
+ entry. In addition, the mandatory and optional fields are also can
+ be varied. In <xref linkend="figfields" />, as an example, the
+ association of the Article entry type can be seen.</para>
+ </sect2>
+ <sect2 id="gui-settings-pref">
+ <title>Preferences</title>
+
+ <para>Clicking on the <menuchoice><guimenu>Settings</guimenu>
+ <guimenuitem>Preferences</guimenuitem></menuchoice> menu item, a
+ lot of configuration options can be controlled. Such options are,
+ for instance, settings of the different type of bibliographic
+ database formats, autosave, size of history, defult editing mode,
+ the default type of a newly created entry, and resource configuration.
+ </para>
+ </sect2>
+ </sect1>
+</chapter>
+
+
+
+<chapter id="command-line">
+ <title>The command line interface</title>
+
+ <para>To start &app; in command line mode, type the following
+ command:</para>
+ <screen>
+ <prompt>bash$ </prompt><userinput>pybliographer</userinput>
+ This is pybliographer, version 1.2.12
+ Copyright (C) 1998-2004 Frederic GOBRY
+ This is free software with ABSOLUTELY NO WARRANTY.
+ For details, type `warranty'.
+ Useful commands:
+ help to get some help
+ quit to quit
+
+ >>
+ </screen>
+
+ <para>To get some help about how to use &app; in this mode, type
+ <command>help</command> at the &pyb; prompt.</para>
+
+ <para>The next example shows how to open a database and make a simple
+ search in it. See the following commands and the output:</para>
+ <screen>
+ >> db = bibopen ("database.bib")
+ >> iterator = search (db, 'author = Mantsch')
+ >> ls (iterator)
+ The Use and Misuse of FTIR Spectro Jackson, Michael; Mantsc [JM95 ]
+ Phospholipid phase transitions in Mantsch, H. H.; McElhane [MM01 ]
+ >>
+ </screen>
+ <para>To see the complete entries listed by the command <command>ls (iterator)</command>:
+ </para>
+ <screen>
+ >> more (iterator)
+ Article [JM95]
+ ----------------------------------------------------------------------
+ Author Jackson, Michael; Mantsch, Henry H.
+ Title The Use and Misuse of FTIR Spectroscopy in the
+ Determination of Protein Structure
+ Journal Critical Reviews in Biochemistry and Molecular Biology
+ Date 1995
+ Volume 30
+ Number 2
+ Pages 95-120
+ keywords infrared spectroscopy; proteins; secondary structure;
+ quantitation
+ comments Review
+
+ Article [MM01]
+ ----------------------------------------------------------------------
+ Author Mantsch, H. H.; McElhaney, R. N.
+ Title Phospholipid phase transitions in model and biological
+ membranes as studied by infrared spectroscopy
+ Journal Chemistry and Physics of Lipids
+ Date 1991
+ Volume 57
+ --More--
+ </screen>
+
+</chapter>
+
+
+
+<chapter id="script-scripting">
+ <title>The scripting language</title>
+
+ <para>&pyb; is in fact a simple set of classes and functions written
+ in python, and that provides with a simple and homogenous access
+ to bibliographic databases. Therefore, it is possible to write
+ python scripts that make use of these specialized functions. The
+ graphical interface, &pyc;, is itself a simple script on top of
+ &pyb;.</para>
+
+ <para>To execute a script written for &pyb;, simply run </para>
+
+ <screen>
+ <prompt>bash$ </prompt><command>pybliographer [--quiet] </command><replaceable>myscript.py</replaceable>
+ </screen>
+
+ <para>You can alternatively start your script by
+ <programlisting>
+ #!/path/to/pybliographer
+
+ ...rest of your script...
+ </programlisting>
+ and make it executable.
+ </para>
+
+ <sect1 id="script-scripting-existing">
+ <title>Existing scripts</title>
+
+ <para>Some scripts are provided with pybliographer, both as
+ example and as useful tools. They are quite short and should be
+ readable with basical knowledge of
+ <productname>python</productname>.</para>
+
+ <sect2 id="script-scripting-existing-pybcheck">
+ <title>pybcheck</title>
+
+ <abstract>
+ <para>This tool takes a list of files or directory, and check
+ if they are valid (syntax, no entries with the same
+ key,...)</para>
+ </abstract>
+
+ <para>It is possible to use its output directly in an emacs
+ compile buffer, in order to jump directly to the encountered
+ errors. To do so, type <keysym>M-x compile</keysym>, then the
+ command <command>pybcheck
+ <filename>yourfiles</filename></command>, and use the middle
+ button of the mouse to jump into the faulty file.</para>
+ </sect2>
+
+ <sect2 id="script-scripting-existing-pybcompact">
+ <title>pybcompact</title>
+
+ <abstract>
+ <para>This tool extracts the citations made in a LaTeX
+ document and generates a BibTeX file containing
+ them.</para>
+ </abstract>
+
+ <para>Usually, one stores its bibliographies in one or several
+ large BibTeX files, and lets <command>bibtex</command> extract
+ the entries used in a LaTeX document. But it is sometime
+ convenient to create a self-contained package (for example to
+ share it in native form with somebody else, or to store it),
+ with a minimalistic BibTeX file holding exactly the entries
+ used in LaTeX. This tool does exactly that: it reads a LaTeX
+ <filename>.aux</filename> file, and extract from the specified
+ BibTeX databases the corresponding entries.</para>
+ </sect2>
+
+ <sect2 id="script-scripting-existing-pybconvert">
+ <title>pybconvert</title>
+
+ <abstract>
+ <para>This tool converts from one bibliographic format to
+ another.</para>
+ </abstract>
+
+ <para>The general syntax is pretty simple. To convert from Refer
+ to BibTeX for example, just run: </para>
+
+ <screen>
+ <prompt>bash$ </prompt><command>pybconvert</command> refer..bibtex <replaceable>toto.refer</replaceable> <replaceable>toto.bib</replaceable>
+ </screen>
+ </sect2>
+
+ <sect2 id="script-scripting-existing-pybformat">
+ <title>pybformat</title>
+
+ <abstract>
+ <para>This script generates a bibliography according to a
+ bibliographic style, and outputs it in a specific format (like
+ HTML, LaTeX,...) as it should appear in a document.</para>
+ </abstract>
+
+ <para>The general form of the command is</para>
+ <screen>
+ <prompt>bash$ </prompt><command>pybformat</command> [options] <filename>database...</filename>
+ </screen>
+
+ <para>This command without options will use the style called
+ <emphasis>alpha</emphasis> to create a bibliography in
+ <emphasis>Text</emphasis> format. Several options are available to
+ create these documents:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><option>--style=... or -s ...</option>: specify a
+ bibliography style. This can be a full path to an existing
+ XML file, or a name which will be searched in the standard
+ places. Default is Alpha.</para>
+ </listitem>
+ <listitem>
+ <para><option>--format=... or -f ...</option>: specify an
+ output format (HTML, LaTeX, Raw, Text, Textau, Textnum). Default is
+ Text. (Textau and Textnum are just slightly modified versions of Text.
+ See <xref linkend="script-scripting-existing-pybtext" /> for more
+ details.)</para>
+ </listitem>
+ <listitem>
+ <para><option>--output=... or -o ...</option>: specify an
+ output filename. STDOUT is the default.</para>
+ </listitem>
+ <listitem>
+ <para><option>--header=... or -H ...</option>: defines a
+ file that will be prepended to the output file.</para>
+ </listitem>
+ <listitem>
+ <para><option>--footer=... or -F ...</option>: defines a
+ file that will be appended to the output file.</para>
+ </listitem>
+ <listitem>
+ <para><option>--list=output or -l output</option>: lists the
+ available output formats</para>
+ </listitem>
+ </itemizedlist>
+
+ </sect2>
+
+ <sect2 id="script-scripting-existing-pybtex">
+ <title>pybtex</title>
+
+ <abstract>
+ <para>This tool searches for the citations in a LaTeX
+ document and generates a LaTeX bibliography file.</para>
+ </abstract>
+
+ <para>This tool reads a LaTeX <filename>.aux</filename> file,
+ and extracting the corresponding entries from the specified
+ BibTeX databases creates a LaTeX bbl file.</para>
+
+ <para>The form of the command is</para>
+ <screen>
+ <prompt>bash$ </prompt><command>pybtex</command> <filename>latexfile</filename> [<filename>bibtexfiles</filename>...]
+ </screen>
+ </sect2>
+
+ <sect2 id="script-scripting-existing-pybtext">
+ <title>pybtext</title>
+
+ <abstract>
+ <para>This tool processes a text file containing citations
+ and appends a bibliography according to a given style.</para>
+ </abstract>
+
+ <para>The script searches for citations like [key] or [key1,key2...]
+ in a text file (for example: ...This is a text fragment with
+ citations [AKM95,MPJ+03] inserted from pybliographer...). First,
+ according to the keys found in the text file,
+ it generates a reference list. Using an appropriate style (see below), it
+ replaces the database keys in the text body with the new keys generated
+ by the style module, and finally it appends the reference list to the
+ text resulting a new file.</para>
+
+ <tip>
+ <para>The keys of selected entries can be copied easily from
+ pybliographer into a text editor or terminal by <emphasis>copy and paste
+ </emphasis> or <emphasis>drag and drop</emphasis>.</para>
+ </tip>
+
+ <para>The general form of the command is</para>
+ <screen>
+ <prompt>bash$ </prompt><command>pybtext</command> [-o outputfile] [-s style] <filename>textfile</filename> <filename>bibfiles...</filename>
+ </screen>
+
+ <para>This command without the options will use the style called
+ <emphasis>Abbrev</emphasis> and <filename>textfile.pyb</filename> as
+ outputfile for processing. <filename>textfile</filename> is the name
+ of the file to be processed and <filename>bibfiles</filename> is one
+ or more bibliographic database file.</para>
+
+ <para>There are three different <emphasis>styles</emphasis> which are
+ designed for pybtext.
+ Using <emphasis>abbrvbib</emphasis> results in keys as they are defined
+ in the database. With the style <emphasis>abbrvau</emphasis>, author-year
+ type keys (e.g. Jackson et al., 2004) can be generated. Using
+ <emphasis>abbrvnum</emphasis>, the script produces a simple numbered list.
+ For abbrvau and abbrvnum, the formats Textau and Textnum are used,
+ respectively. They are just simple modifications of the Text format,
+ optimized for these styles. Using other styles (Alpha, Abbrev
+ or apa4e), the text body is not processed, but the reference list is
+ appended in the form that corresponds to the used style.</para>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="script-scripting-writing">
+ <title>Writing your own scripts</title>
+
+ <para>To start writing your own script, you can read what follows,
+ and then have a look at the existing scripts. Trying to adapt them
+ to fit your personal needs can be a good way of testing what you
+ read.</para>
+
+ <sect2 id="script-scripting-writing-concepts">
+ <title>Some concepts</title>
+
+ <para>This section describes some basic classes and ideas that
+ are useful to understand how &pyb; works.</para>
+
+ <para>In the following, all the modules that will be refered to
+ belong to the <symbol>Pyblio</symbol> domain. So, to access
+ the members of the <symbol>Open</symbol> module, you'll have
+ to write at the beginning of your script something like</para>
+
+ <programlisting>from Pyblio import Open</programlisting>
+
+ <para>The <symbol>Base</symbol> module contains some of the most
+ basical classes used in the application:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><symbol>Base.Entry</symbol> represents a specific
+ bibliographic entry, with all its fields. It behaves like a
+ hash table which returns the content of a field given its
+ name</para>
+ </listitem>
+ <listitem>
+ <para><symbol>Base.DataBase</symbol> is the class from which
+ every database type inherits. It behaves like a hash table
+ that returns a Base.Entry given a Base.Key</para>
+ </listitem>
+ </itemizedlist>
+
+ <para><symbol>Key.Key</symbol> is the object that uniquely
+ identifies an entry. This object must be unique over the
+ whole application, and is composed of a database part and an
+ entry part.</para>
+
+ <para>An <symbol>Iterator</symbol> is an object that provides a
+ way to access a sequence of items in order. These iterators
+ are used extensively in &pyb;, because they hide the
+ underlying access mechanism, and provide the same access on
+ any database. They are also perfectly suited for implementing
+ transparent filtering and sorting of entries: the
+ <symbol>Selection.Selection</symbol> class for example takes
+ an iterator (on a database for example) and return a new one
+ which will only iterate on a subset of the entries, according
+ to a search criterion.</para>
+
+ </sect2>
+
+ </sect1>
+</chapter>
+
+
+
+<chapter id="config-customization">
+ <title>Customization</title>
+
+ <para>The configuration system is heavily based on python's module
+ system. The configuration files are standard &pyb; scripts (that
+ is, python code making use of &pyb; extra classes and functions),
+ whose single special feature is to be automatically parsed at
+ startup or when needed.</para>
+
+ <sect1 id="config-customization-files">
+ <title>Files involved</title>
+
+ <para>The first file to be parsed is
+ <filename>${prefix}/share/pybliographer/pybrc.py</filename>. It
+ serves as a bootstrap for the general configuration mechanism,
+ and defines:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>the available input and output formats</para>
+ </listitem>
+
+ <listitem>
+ <para>where to find the configuration directories.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A configuration directory holds a list of files which are
+ parsed when needed. For example, if a method requires some
+ configuration data for the bibtex module, it will import the
+ corresponding file in this directory.</para>
+
+ <para> This mechanism allows more flexibility to add new formats:
+ the new format can be installed with a default configuration
+ without messing with the global configuration file. In addition,
+ the program imports only what is needed, decreasing its startup
+ time.</para>
+
+ <para>Finally, if the user provides a file called
+ <filename>.pybrc.py</filename> in its home directory, this file
+ is then parsed. Of course it can also define a private
+ configuration directory, and override what has been defined
+ before.</para>
+ </sect1>
+
+ <sect1 id="config-customization-configmodule">
+ <title>The <classname>Config</classname> module</title>
+
+ <para>All the data that can be configured should be handled by the
+ so-called <classname>Config</classname> module. It provides a
+ standard interface to set/get and document configuration
+ items.</para>
+
+ </sect1>
+
+</chapter>
+
+
+
+<chapter id="styles">
+ <title>Creating new Styles</title>
+
+ <para>It is possible to describe your own bibliography style, by
+ writing a simple XML file. The XML file should have the following
+ header:</para>
+
+ <programlisting>
+ <?xml version="1.0"?>
+ </programlisting>
+
+ <para>The whole description should fit in a <bibstyle> pair of
+ tags, whose content is shortly described in this section. It is
+ suggested that the interested users look at the corresponding DTD,
+ which describes the allowed syntax in details. This DTD can be
+ found in the same directory as the default style files.</para>
+
+ <sect1 id="styles-global">
+ <title>Global formatting</title>
+
+ <para>The XML style file describes how the different data fields
+ are organized in order to create a bibliographic style. For
+ example, it can specify that an article starts with the article
+ title in bold, followed by the authors names, etc.</para>
+
+ <para>In its current incarnation, the XML format can however not
+ describe lower-level informations, like how an author's name
+ should be output. This is done by pointing to a set of python
+ functions, grouped in a module. Let's consider the following
+ example:</para>
+
+<programlisting>
+ <module name="generic">
+ <define field="author">full_authors</define>
+ <define field="editor">first_last_full_authors</define>
+ <define field="date">european_date</define>
+ <define method="keys">string_keys</define>
+ </module>
+</programlisting>
+
+ <para>In this example, we require that the
+ <emphasis>author</emphasis> fields should be formatted by the
+ <function>full_authors()</function> function, located in the
+ <filename>generic</filename> module.</para>
+
+ <para>Such a module has to be declared in the
+ <filename>pybrc.py</filename> file, by a line like:
+
+<programlisting>Autoload.preregister ('style','Generic','Pyblio.Style.Generic')</programlisting>
+</para>
+
+ <para>The precise definition of the formatting functions is better
+ explained by looking at the code of
+ <filename>Generic.py</filename> for example.</para>
+
+ </sect1>
+
+ <sect1 id="styles-definition">
+ <title>Bibliography definition</title>
+
+ <para>Once the basic formatting definitions have been specified,
+ it is possible to describe the aspect of the actual
+ bibliographies with following tags:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para> <style name="<varname>stylename</varname>"></para>
+
+ <para>This tag specifies the current display style, among
+ <emphasis>bold, italic, slanted, emph</emphasis>.</para>
+ </listitem>
+
+ <listitem>
+ <para> <inentry name="<varname>entryname</varname>"></para>
+
+ <para>This tag encloses a block that is only to appear in
+ entries of type <varname>entryname</varname>.</para>
+ </listitem>
+
+ <listitem>
+ <para> <notinentry name="<varname>entryname</varname>"></para>
+
+ <para>This tag encloses a block that is only to appear in
+ entries that are <emphasis>not</emphasis> of type
+ <varname>entryname</varname>.</para>
+ </listitem>
+
+ <listitem>
+ <para> <infield name="<varname>fieldname</varname>"></para>
+
+ <para>This tag encloses a block that only appears when the
+ specified <varname>fieldname</varname> field exists in the
+ current entry.</para>
+ </listitem>
+
+ <listitem>
+
+ <para><notinfield name="<varname>fieldname</varname>"></para>
+
+ <para>This tag encloses a block that only appears when the
+ specified <varname>fieldname</varname> field <emphasis>does
+ not</emphasis> exist in the current entry.</para>
+ </listitem>
+
+ <listitem>
+ <para> <content <optional>name="<varname>fieldname</varname>"</optional>/></para>
+
+ <para>This empty tag is replaced by the content of the current
+ field (when placed in a <infield> block) or the content of
+ the field specified as attribute.</para>
+ </listitem>
+
+ <listitem>
+ <para> <separator></para>
+
+ <para>This tag's content evaluates to nothing when no text has
+ been issued so far. It is a convenient way to add a delimiter
+ after a series of fields without being worried of the special
+ case when the fields are not defined.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>The existing style files are a good source of examples.</para>
+ </sect1>
+
+ <sect1 id="styles-future">
+ <title>Future of the format</title>
+
+ <para>In the future, this rudimentary format will most likely be
+ replaced with an XSL-based mechanism, which should encompass both
+ the XML definition and the python modules, thus providing
+ standalone style files, parsable by any XSL parser.</para>
+ </sect1>
+</chapter>
+
+
+
+<appendix id="authors">
+ <title>Authors</title>
+ <para><application>&app;</application> was originally written by
+ Frédéric Gobry. Many thanks to all contributors for their fruitful
+ work.</para>
+
+ <para><emphasis>Contributions:</emphasis></para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Yuri Bongiorno</term>
+ <listitem>
+ <para>documentation, translations</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Hervé Dréau</term>
+ <listitem>
+ <para>internationalization, UI goodies</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Frédéric Gobry</term>
+ <listitem>
+ <para>project maintainer, core application, Gnome
+ interface, documentation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Zoltán Kóta</term>
+ <listitem>
+ <para>documentation, packaging, ui code</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Travis Oliphant</term>
+ <listitem>
+ <para>original Ovid parser</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Darrell Rudmann</term>
+ <listitem>
+ <para>APA 4th edition style</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Peter Schulte-Stracke</term>
+ <listitem>
+ <para>application design, requirement docs, import
+ and ui code</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>John Vu</term>
+ <listitem>
+ <para>Medline database parser</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Thanks to everyone who helped out with the bug tracking process.
+ </para>
+ <para>
+ Many thanks also to the Documentation Translators and the Gnome
+ Translation Teams.
+ </para>
+ <para>
+ This manual was written with the help of the GNOME Documentation
+ Project.
+ </para>
+ <para>
+ If you contributed to this project but do not see your name here,
+ please contact the project maintainer and he'll list you.
+ </para>
+ <para>
+ For more information please visit the
+ <application>&app;</application> <ulink
+ url="http://www.pybliographer.org"; type="http">website</ulink>.
+ </para>
+</appendix>
+
+</book>
diff --git a/doc/Makefile.am b/help/Makefile.am
similarity index 100%
rename from doc/Makefile.am
rename to help/Makefile.am
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
