[pybliographer] Completed first draft of the Mallard manual
- From: Mario Blättermann <mariobl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [pybliographer] Completed first draft of the Mallard manual
- Date: Sun, 7 Nov 2010 15:05:57 +0000 (UTC)
commit a3b929de472ac98aea7725e556e56c9dc9e99799
Author: Mario Blättermann <mariobl gnome org>
Date: Sun Nov 7 16:03:33 2010 +0100
Completed first draft of the Mallard manual
help/C/about.page | 4 +-
help/C/addhelp.page | 11 +-
help/C/command-line.page | 98 ++++++++++++++++++++
help/C/gettingstarted.page | 16 +---
help/C/gui-formats.page | 44 +++++++++
help/C/gui-navigating.page | 2 +-
help/C/gui-pubmed.page | 43 +++++++++
help/C/gui-settings.page | 112 ++++++++++++++++++++++
help/C/gui-styles.page | 159 +++++++++++++++++++++++++++++++
help/C/gui-usinglyx.page | 52 ++++++++++
help/C/index.page | 8 --
help/C/scripting-basics.page | 48 ++++++++++
help/C/scripting-existing.page | 200 ++++++++++++++++++++++++++++++++++++++++
help/C/scripting-writeown.page | 80 ++++++++++++++++
14 files changed, 848 insertions(+), 29 deletions(-)
---
diff --git a/help/C/about.page b/help/C/about.page
index fe3084f..cd7b5b0 100644
--- a/help/C/about.page
+++ b/help/C/about.page
@@ -61,7 +61,7 @@
</p>
<p>
For more information please visit the
- <app>Pybliographer</app> <link href="http://pybliographer.org/";
- type="http">website</link>.
+ <link href="http://pybliographer.org/";
+ type="http"><app>Pybliographer</app> website</link>.
</p>
</page>
diff --git a/help/C/addhelp.page b/help/C/addhelp.page
index 6e34a84..b60a80c 100644
--- a/help/C/addhelp.page
+++ b/help/C/addhelp.page
@@ -23,11 +23,12 @@
</info>
<title>Additional Help Sources</title>
- <p>For additional information, please, visit the Pybliographer
- website at
- <link href="http://pybliographer.org/"; type="http">http://pybliographer.org</link>.
- There is a mailing list also, where you can get answers for your
- questions, you can report bugs, etc.
+ <p>For additional information, please, visit the
+ <link href="http://pybliographer.org/"; type="http">Pybliographer
+ website</link>.
+ There is a <link href="http://pybliographer.org/Mailing_lists";
+ type="http">mailing list</link> also, where you can get answers
+ for your questions, you can report bugs, etc.
</p>
</page>
diff --git a/help/C/command-line.page b/help/C/command-line.page
new file mode 100644
index 0000000..af7c3dc
--- /dev/null
+++ b/help/C/command-line.page
@@ -0,0 +1,98 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ xmlns:e="http://projectmallard.org/experimental/";
+ type="guide"
+ id="command-line">
+
+ <info>
+ <link type="guide" xref="index#usage"/>
+ <revision pkgversion="3.0" version="0.1" date="2010-10-24" status="incomplete"/>
+ <desc>
+ Using <app>Pybliographer</app> with a terminal.
+ </desc>
+ <credit type="author">
+ <name>Zoltán Kóta</name>
+ <email>zoltank gmail com</email>
+ </credit>
+ <credit type="author">
+ <name>Frédéric Gobry</name>
+ <email>frederic gobry epfl ch</email>
+ </credit>
+ <license>
+ <p>Creative Commons Share Alike 3.0</p>
+ </license>
+ </info>
+
+ <title>The command line interface</title>
+
+ <p>To start <app>Pybliographer</app> in command line mode, type the following
+ command:</p>
+ <screen>
+ <output>bash$ </output><input>pybliographer</input>
+ 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>
+
+ <p>To get some help about how to use <app>Pybliographer</app> in this
+ mode, type <cmd>help</cmd> at the <app>Pybliographer</app> prompt.</p>
+
+ <p>The next example shows how to open a database and make a simple
+ search in it. See the following commands and the output:</p>
+ <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>
+ <p>To see the complete entries listed by the command <cmd>ls (iterator)</cmd>:
+ </p>
+ <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>
+
+
+ <p>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:</p>
+ <screen>
+ <output>bash$ </output><input>export PYBLIOGRAPHER_DATABASE=<var>my/database.bib</var></input>
+ <output>bash$ </output><input>pybliographic</input>
+ </screen>
+ <p>It is equivalent to</p>
+ <screen>
+ <output>bash$ </output><input>pybliographic <var>my/database.bib</var></input>
+ </screen>
+
+
+</page>
diff --git a/help/C/gettingstarted.page b/help/C/gettingstarted.page
index f472a21..019b223 100644
--- a/help/C/gettingstarted.page
+++ b/help/C/gettingstarted.page
@@ -47,14 +47,15 @@
command line, type the following command, then press
<key>Return</key>: <cmd>pybliographic</cmd>.
For more information on the graphical interface, see
- <link xref="gui"/>.
+ <link xref="gui"/>.
</desc>
</item>
<item><p>Command line mode</p>
<desc>
You can start <app>Pybliographic</app> also in command
line mode by typing the following command followed by pressing
- <key>Return</key>: <cmd>pybliographer</cmd>.
+ <key>Return</key>: <cmd>pybliographer</cmd>. For more
+ information, see <link xref="command-line"/>.
</desc>
</item>
<item><p>From the GNOME menu</p>
@@ -66,17 +67,6 @@
</item>
</list>
- <p>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:</p>
- <screen>
- <output>bash$ </output><input>export PYBLIOGRAPHER_DATABASE=<var>my/database.bib</var></input>
- <output>bash$ </output><input>pybliographic</input>
- </screen>
- <p>It is equivalent to</p>
- <screen>
- <output>bash$ </output><input>pybliographic <var>my/database.bib</var></input>
- </screen>
</section>
</page>
diff --git a/help/C/gui-formats.page b/help/C/gui-formats.page
new file mode 100644
index 0000000..8eeb41f
--- /dev/null
+++ b/help/C/gui-formats.page
@@ -0,0 +1,44 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ xmlns:e="http://projectmallard.org/experimental/";
+ type="guide"
+ id="gui-formats">
+
+ <info>
+ <link type="guide" xref="gui"/>
+ <revision pkgversion="3.0" version="0.1" date="2010-10-24" status="incomplete"/>
+ <desc>
+ Other file formats which you can also use.
+ </desc>
+ <credit type="author">
+ <name>Zoltán Kóta</name>
+ <email>zoltank gmail com</email>
+ </credit>
+ <credit type="author">
+ <name>Frédéric Gobry</name>
+ <email>frederic gobry epfl ch</email>
+ </credit>
+ <license>
+ <p>Creative Commons Share Alike 3.0</p>
+ </license>
+ </info>
+
+ <title>Saving selected entries in different formats</title>
+
+ <p>Selected entries can be saved in different formats using
+ the <guiseq><gui>Cite</gui><gui>Format...</gui></guiseq> menu item
+ (<link xref="figformat" />).
+ </p>
+
+ <p><media type="image" mime="image/png" src="figures/format.png">
+ Formatting entries
+ </media></p>
+
+
+ <p>As a result, a formatted output file is generated according
+ to a bibliographic style, either in HTML, LaTeX, Raw or Text format.
+ The <app>Pybliographer</app> package contains some bibliographic styles,
+ but own styles can also be created easily. See also
+ <link xref="script-scripting-existing-pybformat" />.</p>
+
+ </page>
+
diff --git a/help/C/gui-navigating.page b/help/C/gui-navigating.page
index 8d288bb..b67fa17 100644
--- a/help/C/gui-navigating.page
+++ b/help/C/gui-navigating.page
@@ -7,7 +7,7 @@
<link type="guide" xref="gui"/>
<revision pkgversion="3.0" version="0.1" date="2010-10-24" status="incomplete"/>
<desc>
- Explanations about the graphical interface of <app>Pybliographer</app>.
+ Explanations about the navigation in the database.
</desc>
<credit type="author">
<name>Zoltán Kóta</name>
diff --git a/help/C/gui-pubmed.page b/help/C/gui-pubmed.page
new file mode 100644
index 0000000..9c3bde7
--- /dev/null
+++ b/help/C/gui-pubmed.page
@@ -0,0 +1,43 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ xmlns:e="http://projectmallard.org/experimental/";
+ type="guide"
+ id="gui-pubmed">
+
+ <info>
+ <link type="guide" xref="gui"/>
+ <revision pkgversion="3.0" version="0.1" date="2010-10-24" status="incomplete"/>
+ <desc>
+ Using Pubmed for your searches.
+ </desc>
+ <credit type="author">
+ <name>Zoltán Kóta</name>
+ <email>zoltank gmail com</email>
+ </credit>
+ <credit type="author">
+ <name>Frédéric Gobry</name>
+ <email>frederic gobry epfl ch</email>
+ </credit>
+ <license>
+ <p>Creative Commons Share Alike 3.0</p>
+ </license>
+ </info>
+
+ <title>Searching in PubMed</title>
+
+ <p>With <app>Pybliographic</app>, it is possible to perform a Medline search.
+ To use this option, click on the <guiseq><gui>File</gui><gui>Medline query...
+ </gui></guiseq> menu item. The upcoming window is represented in
+ <link xref="figmed" />.</p>
+
+ <p><media type="image" mime="image/png" src="figures/medline.png">
+ Medline query
+ </media></p>
+
+ <p>The keyword, you are looking for, should be written into the
+ <em>Search PubMed for</em> field. As it can be seen in <link xref="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.</p>
+
+ </page>
+
diff --git a/help/C/gui-settings.page b/help/C/gui-settings.page
new file mode 100644
index 0000000..516437b
--- /dev/null
+++ b/help/C/gui-settings.page
@@ -0,0 +1,112 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ xmlns:e="http://projectmallard.org/experimental/";
+ type="guide"
+ id="gui-settings">
+
+ <info>
+ <link type="guide" xref="gui"/>
+ <revision pkgversion="3.0" version="0.1" date="2010-10-24" status="incomplete"/>
+ <desc>
+ How to customize this application to match your needs.
+ </desc>
+ <credit type="author">
+ <name>Zoltán Kóta</name>
+ <email>zoltank gmail com</email>
+ </credit>
+ <credit type="author">
+ <name>Frédéric Gobry</name>
+ <email>frederic gobry epfl ch</email>
+ </credit>
+ <license>
+ <p>Creative Commons Share Alike 3.0</p>
+ </license>
+ </info>
+
+ <title>Configuration</title>
+
+ <p>Under the <guiseq><gui>Settings</gui></guiseq> menu, you can find some
+ options to customize <app>Pybliographer</app>.</p>
+
+ <section id="gui-settings-fields">
+ <title>Entry types and field names configuration</title>
+
+ <p><media id="figfields" type="image" mime="image/png" src="figures/fields.png">
+ Configuration of fields and entry types
+ </media></p>
+
+ <p>Selecting the <guiseq><gui>Settings</gui><gui>Fields</gui>
+ </guiseq> 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 <link xref="figfields"/>, as an example, the association of
+ the Article entry type can be seen.</p>
+ </section>
+ <section id="gui-settings-pref">
+ <title>Preferences</title>
+
+ <p>Clicking on the <guiseq><gui>Settings</gui><gui>Preferences</gui>
+ </guiseq> 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, default editing
+ mode, the default type of a newly created entry, and resource configuration.
+ </p>
+ </section>
+
+ <section>
+ <title>Advanced Configuration</title>
+
+ <p>The configuration system is heavily based on <app>Python</app>'s
+ module system. The configuration files are standard <app>Pybliographer</app>
+ scripts (that is, python code making use of <app>Pybliographer</app>
+ extra classes and functions), whose single special feature is to be
+ automatically parsed at startup or when needed.</p>
+
+ <section id="config-customization-files">
+ <title>Files involved</title>
+
+ <p>The first file to be parsed is <file>${prefix}/share/pybliographer/pybrc.py
+ </file>. It serves as a bootstrap for the general configuration mechanism,
+ and defines:</p>
+
+ <list>
+ <item>
+ <p>the available input and output formats</p>
+ </item>
+
+ <item>
+ <p>where to find the configuration directories.</p>
+ </item>
+ </list>
+
+ <p>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.</p>
+
+ <p> 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.</p>
+
+ <p>Finally, if the user provides a file called <file>.pybrc.py</file>
+ 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.</p>
+ </section>
+
+ <section id="config-customization-configmodule">
+ <title>The <classname>Config</classname> module</title>
+
+ <p>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.</p>
+
+
+ </section>
+ </section>
+
+
+ </page>
+
diff --git a/help/C/gui-styles.page b/help/C/gui-styles.page
new file mode 100644
index 0000000..06e92b1
--- /dev/null
+++ b/help/C/gui-styles.page
@@ -0,0 +1,159 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ xmlns:e="http://projectmallard.org/experimental/";
+ type="guide"
+ id="gui-styles">
+
+ <info>
+ <link type="guide" xref="gui"/>
+ <revision pkgversion="3.0" version="0.1" date="2010-10-24" status="incomplete"/>
+ <desc>
+ Creating your own styles for <app>Pybliographer</app>.
+ </desc>
+ <credit type="author">
+ <name>Zoltán Kóta</name>
+ <email>zoltank gmail com</email>
+ </credit>
+ <credit type="author">
+ <name>Frédéric Gobry</name>
+ <email>frederic gobry epfl ch</email>
+ </credit>
+ <license>
+ <p>Creative Commons Share Alike 3.0</p>
+ </license>
+ </info>
+
+ <title>New Styles</title>
+
+ <p>It is possible to describe your own bibliography style, by
+ writing a simple XML file. The XML file should have the following
+ header:</p>
+
+ <screen>
+ <?xml version="1.0"?>
+ </screen>
+
+ <p>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.</p>
+
+ <section id="styles-global">
+ <title>Global formatting</title>
+
+ <p>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.</p>
+
+ <p>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:</p>
+
+<code>
+ <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>
+</code>
+
+ <p>In this example, we require that the
+ <em>author</em> fields should be formatted by the
+ <code>full_authors()</code> function, located in the
+ <file>generic</file> module.</p>
+
+ <p>Such a module has to be declared in the
+ <file>pybrc.py</file> file, by a line like:
+
+<code>Autoload.preregister ('style','Generic','Pyblio.Style.Generic')</code>
+</p>
+
+ <p>The precise definition of the formatting functions is better
+ explained by looking at the code of <file>Generic.py</file> for example.</p>
+
+ </section>
+
+ <section id="styles-definition">
+ <title>Bibliography definition</title>
+
+ <p>Once the basic formatting definitions have been specified,
+ it is possible to describe the aspect of the actual bibliographies
+ with following tags:</p>
+
+ <list>
+ <item>
+ <p> <style name="<var>stylename</var>"></p>
+
+ <p>This tag specifies the current display style, among
+ <em>bold, italic, slanted, emph</em>.</p>
+ </item>
+
+ <item>
+ <p> <inentry name="<var>entryname</var>"></p>
+
+ <p>This tag encloses a block that is only to appear in
+ entries of type <var>entryname</var>.</p>
+ </item>
+
+ <item>
+ <p> <notinentry name="<var>entryname</var>"></p>
+
+ <p>This tag encloses a block that is only to appear in
+ entries that are <em>not</em> of type
+ <var>entryname</var>.</p>
+ </item>
+
+ <item>
+ <p> <infield name="<var>fieldname</var>"></p>
+
+ <p>This tag encloses a block that only appears when the
+ specified <var>fieldname</var> field exists in the
+ current entry.</p>
+ </item>
+
+ <item>
+
+ <p><notinfield name="<var>fieldname</var>"></p>
+
+ <p>This tag encloses a block that only appears when the specified
+ <var>fieldname</var> field <em>does not</em> exist in the current
+ entry.</p>
+ </item>
+
+ <item>
+ <p> <content <var>name=</var>"<var>fieldname</var>"/></p>
+
+ <p>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.</p>
+ </item>
+
+ <item>
+ <p> <separator></p>
+
+ <p>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.</p>
+ </item>
+
+ </list>
+
+ <p>The existing style files are a good source of examples.</p>
+ </section>
+
+ <section id="styles-future">
+ <title>Future of the format</title>
+
+ <p>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.</p>
+ </section>
+
+ </page>
+
diff --git a/help/C/gui-usinglyx.page b/help/C/gui-usinglyx.page
new file mode 100644
index 0000000..96213e2
--- /dev/null
+++ b/help/C/gui-usinglyx.page
@@ -0,0 +1,52 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ xmlns:e="http://projectmallard.org/experimental/";
+ type="guide"
+ id="gui-usinglyx">
+
+ <info>
+ <link type="guide" xref="gui"/>
+ <revision pkgversion="3.0" version="0.1" date="2010-10-24" status="incomplete"/>
+ <desc>
+ Interaction with the <app>LyX</app> document processor.
+ </desc>
+ <credit type="author">
+ <name>Zoltán Kóta</name>
+ <email>zoltank gmail com</email>
+ </credit>
+ <credit type="author">
+ <name>Frédéric Gobry</name>
+ <email>frederic gobry epfl ch</email>
+ </credit>
+ <license>
+ <p>Creative Commons Share Alike 3.0</p>
+ </license>
+ </info>
+
+<title>Using <app>Pybliographic</app> with <app>LyX</app></title>
+
+ <p>It is possible to directly use <app>Pybliographer</app> in order
+ to insert bibliographic references into <app>LyX</app>. It is done
+ through the <app>LyX</app> <em>server</em>. The path of the <app>LyX</app>
+ server pipe can be defined in the <guiseq><gui>Tools</gui>
+ <gui>Preferences</gui></guiseq> dialog of LyX.
+ The same path should be given in <app>Pybliographer</app>'s settings
+ (the default value is <file>~/.lyx/lyxpipe)</file>.</p>
+
+ <p>Then, in <app>Pybliographic</app>, it is possible to select one or
+ several entries and insert their references into a running <app>LyX</app>
+ simply by clicking the <gui>Cite</gui> toolbar button, or selecting the
+ <guiseq><gui>Cite</gui><gui>Cite...</gui></guiseq> menu item.</p>
+
+ <p>For the moment, it is the user's job to ensure that he/she
+ inserts entries corresponding to the actual database being used.
+ <app>Pybliographic</app> does not handle the full job of bibliography
+ generation; therefore it is necessary to use <cmd>bibtex</cmd> as
+ described in the <app>LyX</app> documentation.</p>
+ <note>
+ <p><app>Pybliographic</app> can interact with <app>Kile</app>
+ (>= 1.6) practically in the same way, since <app>Kile</app> can also
+ read <em>lyx pipe</em>.</p>
+ </note>
+
+ </page>
+
diff --git a/help/C/index.page b/help/C/index.page
index 53c7e2d..774576e 100644
--- a/help/C/index.page
+++ b/help/C/index.page
@@ -37,12 +37,4 @@
<title>The Scripting Language</title>
</section>
- <section id="custom" style="2column">
- <title>Customization</title>
- </section>
-
- <section id="newstyles" style="2column">
- <title>Creating New Styles</title>
- </section>
-
</page>
diff --git a/help/C/scripting-basics.page b/help/C/scripting-basics.page
new file mode 100644
index 0000000..8b542bc
--- /dev/null
+++ b/help/C/scripting-basics.page
@@ -0,0 +1,48 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ xmlns:e="http://projectmallard.org/experimental/";
+ type="guide"
+ id="scripting-basics">
+
+ <info>
+ <link type="guide" xref="index#scripting"/>
+ <revision pkgversion="3.0" version="0.1" date="2010-10-24" status="incomplete"/>
+ <desc>
+ Basic information about scripting with <app>Pybliographer</app>.
+ </desc>
+ <credit type="author">
+ <name>Zoltán Kóta</name>
+ <email>zoltank gmail com</email>
+ </credit>
+ <credit type="author">
+ <name>Frédéric Gobry</name>
+ <email>frederic gobry epfl ch</email>
+ </credit>
+ <license>
+ <p>Creative Commons Share Alike 3.0</p>
+ </license>
+ </info>
+
+ <title>Basics</title>
+
+ <p><app>Pybliographer</app> 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, <app>Pybliographic</app>, is itself a simple
+ script on top of <app>Pybliographer</app>.</p>
+
+ <p>To execute a script written for <app>Pybliographer</app>, simply run </p>
+
+ <screen>
+ <output>bash$ </output><cmd>pybliographer [--quiet] </cmd><var>myscript.py</var>
+ </screen>
+
+ <p>You can alternatively start your script by</p>
+ <screen>
+ #!/path/to/pybliographer
+
+ <var>...rest of your script...</var>
+ </screen>
+ <p>and make it executable.</p>
+
+</page>
diff --git a/help/C/scripting-existing.page b/help/C/scripting-existing.page
new file mode 100644
index 0000000..3988f89
--- /dev/null
+++ b/help/C/scripting-existing.page
@@ -0,0 +1,200 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ xmlns:e="http://projectmallard.org/experimental/";
+ type="guide"
+ id="scripting-existing">
+
+ <info>
+ <link type="guide" xref="index#scripting"/>
+ <revision pkgversion="3.0" version="0.1" date="2010-10-24" status="incomplete"/>
+ <desc>
+ How to use existing scripts.
+ </desc>
+ <credit type="author">
+ <name>Zoltán Kóta</name>
+ <email>zoltank gmail com</email>
+ </credit>
+ <credit type="author">
+ <name>Frédéric Gobry</name>
+ <email>frederic gobry epfl ch</email>
+ </credit>
+ <license>
+ <p>Creative Commons Share Alike 3.0</p>
+ </license>
+ </info>
+
+ <title>Existing scripts</title>
+
+ <p>Some scripts are provided with <app>Pybliographer</app>, both as
+ example and as useful tools. They are quite short and should be
+ readable with basical knowledge of <app>Python</app>.</p>
+
+ <section id="script-scripting-existing-pybcheck">
+ <title>pybcheck</title>
+
+ <synopsis>
+ <p>This tool takes a list of files or directory, and check if
+ they are valid (syntax, no entries with the same key,...)</p>
+ </synopsis>
+
+ <p>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 <keyseq><key>M</key><key>x</key></keyseq>
+ <cmd>compile</cmd>, then the command <cmd>pybcheck
+ <var>yourfiles</var></cmd>, and use the middle button of the
+ mouse to jump into the faulty file.</p>
+ </section>
+
+ <section id="script-scripting-existing-pybcompact">
+ <title>pybcompact</title>
+
+ <synopsis>
+ <p>This tool extracts the citations made in a LaTeX
+ document and generates a BibTeX file containing
+ them.</p>
+ </synopsis>
+
+ <p>Usually, one stores its bibliographies in one or several large
+ BibTeX files, and lets <cmd>bibtex</cmd> 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 <file>.aux</file> file, and extract from the
+ specified BibTeX databases the corresponding entries.</p>
+ </section>
+
+ <section id="script-scripting-existing-pybconvert">
+ <title>pybconvert</title>
+
+ <synopsis>
+ <p>This tool converts from one bibliographic format to
+ another.</p>
+ </synopsis>
+
+ <p>The general syntax is pretty simple. To convert from Refer
+ to BibTeX for example, just run: </p>
+
+ <screen>
+ <output>bash$ </output><cmd>pybconvert</cmd> refer..bibtex <var>toto.refer</var> <var>toto.bib</var>
+ </screen>
+ </section>
+
+ <section id="script-scripting-existing-pybformat">
+ <title>pybformat</title>
+
+ <synopsis>
+ <p>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.</p>
+ </synopsis>
+
+ <p>The general form of the command is</p>
+ <screen>
+ <output>bash$ </output><cmd>pybformat</cmd> <var>[options] database...</var>
+ </screen>
+
+ <p>This command without options will use the style called
+ <em>alpha</em> to create a bibliography in
+ <em>Text</em> format. Several options are available to
+ create these documents:</p>
+
+ <list>
+ <item>
+ <p><cmd>--style=...</cmd> or <cmd>-s ...</cmd>: 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.</p>
+ </item>
+ <item>
+ <p><cmd>--format=...</cmd> or <cmd>-f ...</cmd>: specify an
+ output format (HTML, LaTeX, Raw, Text, Textau, Textnum). Default is
+ Text. (Textau and Textnum are just slightly modified versions of Text.
+ See <link xref="script-scripting-existing-pybtext" /> for more
+ details.)</p>
+ </item>
+ <item>
+ <p><cmd>--output=...</cmd> or <cmd>-o ...</cmd>: specify an
+ output filename. STDOUT is the default.</p>
+ </item>
+ <item>
+ <p><cmd>--header=...</cmd> or <cmd>-H ...</cmd>: defines a
+ file that will be prepended to the output file.</p>
+ </item>
+ <item>
+ <p><cmd>--footer=...</cmd> or <cmd>-F ...</cmd>: defines a
+ file that will be appended to the output file.</p>
+ </item>
+ <item>
+ <p><cmd>--list=output</cmd> or <cmd>-l output</cmd>: lists the
+ available output formats</p>
+ </item>
+ </list>
+ </section>
+
+ <section id="script-scripting-existing-pybtex">
+ <title>pybtex</title>
+
+ <synopsis>
+ <p>This tool searches for the citations in a LaTeX
+ document and generates a LaTeX bibliography file.</p>
+ </synopsis>
+
+ <p>This tool reads a LaTeX <file>.aux</file> file, and extracting
+ the corresponding entries from the specified BibTeX databases
+ creates a LaTeX <file>.bbl</file> file.</p>
+
+ <p>The form of the command is</p>
+ <screen>
+ <output>bash$ </output><cmd>pybtex</cmd> <file>latexfile</file> [<file>bibtexfiles</file>...]
+ </screen>
+ </section>
+
+ <section id="script-scripting-existing-pybtext">
+ <title>pybtext</title>
+
+ <synopsis>
+ <p>This tool processes a text file containing citations
+ and appends a bibliography according to a given style.</p>
+ </synopsis>
+
+ <p>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.</p>
+
+ <note>
+ <p>The keys of selected entries can be copied easily from
+ pybliographer into a text editor or terminal by <em>copy and paste
+ </em> or <em>drag and drop</em>.</p>
+ </note>
+
+ <p>The general form of the command is</p>
+ <screen>
+ <output>bash$ </output><cmd>pybtext</cmd> [-o outputfile] [-s style] <file>textfile</file> <file>bibfiles...</file>
+ </screen>
+
+ <p>This command without the options will use the style called
+ <em>Abbrev</em> and <file>textfile.pyb</file> as
+ outputfile for processing. <file>textfile</file> is the name
+ of the file to be processed and <file>bibfiles</file> is one
+ or more bibliographic database file.</p>
+
+ <p>There are three different <em>styles</em> which are
+ designed for pybtext.
+ Using <em>abbrvbib</em> results in keys as they are defined
+ in the database. With the style <em>abbrvau</em>, author-year
+ type keys (e.g. Jackson et al., 2004) can be generated. Using
+ <em>abbrvnum</em>, 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.</p>
+
+ </section>
+
+</page>
diff --git a/help/C/scripting-writeown.page b/help/C/scripting-writeown.page
new file mode 100644
index 0000000..f0bc75d
--- /dev/null
+++ b/help/C/scripting-writeown.page
@@ -0,0 +1,80 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ xmlns:e="http://projectmallard.org/experimental/";
+ type="guide"
+ id="scripting-writeown">
+
+ <info>
+ <link type="guide" xref="index#scripting"/>
+ <revision pkgversion="3.0" version="0.1" date="2010-10-24" status="incomplete"/>
+ <desc>
+ Writing your own scripts.
+ </desc>
+ <credit type="author">
+ <name>Zoltán Kóta</name>
+ <email>zoltank gmail com</email>
+ </credit>
+ <credit type="author">
+ <name>Frédéric Gobry</name>
+ <email>frederic gobry epfl ch</email>
+ </credit>
+ <license>
+ <p>Creative Commons Share Alike 3.0</p>
+ </license>
+ </info>
+
+ <title>Writing your own scripts</title>
+
+ <p>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.</p>
+
+ <section id="script-scripting-writing-concepts">
+ <title>Some concepts</title>
+
+ <p>This section describes some basic classes and ideas that
+ are useful to understand how <app>Pybliographer</app> works.</p>
+
+ <p>In the following, all the modules that will be refered to
+ belong to the <em>Pyblio</em> domain. So, to access
+ the members of the <em>Open</em> module, you'll have
+ to write at the beginning of your script something like</p>
+
+ <screen>from Pyblio import Open</screen>
+
+ <p>The <em>Base</em> module contains some of the most
+ basical classes used in the application:</p>
+
+ <list>
+ <item>
+ <p><em>Base.Entry</em> 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</p>
+ </item>
+ <item>
+ <p><em>Base.DataBase</em> is the class from which every database
+ type inherits. It behaves like a hash table that returns a
+ Base.Entry given a Base.Key</p>
+ </item>
+ </list>
+
+ <p><em>Key.Key</em> 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.</p>
+
+ <p>An <em>Iterator</em> is an object that provides a
+ way to access a sequence of items in order. These iterators are
+ used extensively in <app>Pybliographer</app>, 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
+ <em>Selection.Selection</em> 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.</p>
+
+ </section>
+
+
+</page>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
