<page xmlns="http://projectmallard.org/1.0/"
      xmlns:e="http://projectmallard.org/experimental/"
      type="guide"
      id="gui-styles">

  <info>
    <link type="guide" xref="index#advusage"/>
    <revision pkgversion="1.2.14" version="0.1" date="2010-05-04" status="incomplete"/>
    <revision pkgversion="1.2.15" version="0.2" date="2010-11-29" status="final"/>
    <desc>
      Creating your own styles for <app>Pybliographer</app>.
    </desc>
    <credit type="author">
      <name>Zolt&#225;n K&#243;ta</name>
      <email>zoltank@gmail.com</email>
    </credit>
    <credit type="author">
      <name>Fr&#233;d&#233;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>
      &lt;?xml version="1.0"?&gt;
    </screen>
    
  <p>The whole description should fit in a &lt;bibstyle&gt; 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>
    
<screen><code>
  &lt;module name="generic">
    &lt;define field="author">full_authors&lt;/define>
    &lt;define field="editor">first_last_full_authors&lt;/define>
    &lt;define field="date">european_date&lt;/define>
    &lt;define method="keys">string_keys&lt;/define>
  &lt;/module>
</code></screen>

    <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:</p>

    <screen><code>Autoload.preregister ('style','Generic','Pyblio.Style.Generic')</code>
</screen>

    <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>	&lt;style name="<var>stylename</var>"&gt;</p>

	<p>This tag specifies the current display style, among
	<em>bold, italic, slanted, emph</em>.</p>
      </item>

      <item>
	<p>	&lt;inentry name="<var>entryname</var>"&gt;</p>

	<p>This tag encloses a block that is only to appear in
	entries of type <var>entryname</var>.</p>
      </item>

      <item>
	<p>	&lt;notinentry name="<var>entryname</var>"&gt;</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>	&lt;infield name="<var>fieldname</var>"&gt;</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>&lt;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>	&lt;content <var>name=</var>"<var>fieldname</var>"/&gt;</p>

	<p>This empty tag is replaced by the content of the current
	field (when placed in a &lt;infield> block) or the content of
	the field specified as attribute.</p>
      </item>

      <item>
	<p>	&lt;separator&gt;</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>

