[Refdb-cvs] CVS: refdb/doc refdb-manual-chapter1.sgml,1.12,1.12.2.1 refdb-manual-chapter10.sgml,1.19
Status: Beta
Brought to you by:
mhoenicka
Menu
▾
▴
[Refdb-cvs] CVS: refdb/doc refdb-manual-chapter1.sgml,1.12,1.12.2.1 refdb-manual-chapter10.sgml,1.19,1.19.2.1 refdb-manual-chapter12.sgml,1.11,1.11.2.1 refdb-manual-chapter13.sgml,1.16,1.16.2.1 refdb-manual-chapter14.sgml,1.9,1.9.2.1 refdb-manual-chapter15.sgml,1.9,1.9.2.1 refdb-manual-chapter2.sgml,1.15,1.15.2.1 refdb-manual-chapter3.sgml,1.12,1.12.2.1 refdb-manual-chapter4.sgml,1.14,1.14.2.1 refdb-manual-chapter5.sgml,1.24,1.24.2.1 refdb-manual-chapter6.sgml,1.17,1.17.2.1 refdb-manual-chapter7.sgml,1.16,1.16.2.1 refdb-manual-chapter8.sgml,1.13,1.13.2.1 refdb-manual-chapter9.sgml,1.15,1.15.2.1 refdb-manual-configopts.sgml,1.4,1.4.2.1 refdb-manual.sgml,1.16,1.16.2.1
Update of /cvsroot/refdb/refdb/doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv25085 Modified Files: Tag: Release_0_9_5_stable refdb-manual-chapter1.sgml refdb-manual-chapter10.sgml refdb-manual-chapter12.sgml refdb-manual-chapter13.sgml refdb-manual-chapter14.sgml refdb-manual-chapter15.sgml refdb-manual-chapter2.sgml refdb-manual-chapter3.sgml refdb-manual-chapter4.sgml refdb-manual-chapter5.sgml refdb-manual-chapter6.sgml refdb-manual-chapter7.sgml refdb-manual-chapter8.sgml refdb-manual-chapter9.sgml refdb-manual-configopts.sgml refdb-manual.sgml Log Message: updated for 0.9.5 Index: refdb-manual-chapter1.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter1.sgml,v retrieving revision 1.12 retrieving revision 1.12.2.1 diff -u -U2 -r1.12 -r1.12.2.1 --- refdb-manual-chapter1.sgml 8 Feb 2004 00:32:45 -0000 1.12 +++ refdb-manual-chapter1.sgml 14 Nov 2004 16:04:49 -0000 1.12.2.1 @@ -1,7 +1,7 @@ -<!DOCTYPE CHAPTER PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ +<!DOCTYPE CHAPTER PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ <!ENTITY appname "refdb"> ]> <!-- $Id$ --> -<chapter> +<chapter id="chapter-introduction"> <title>Introduction</title> <sect1> @@ -32,5 +32,5 @@ <figure float="0" id="figure-threetier"> <title>&appname; three-tier architecture</title> - <graphic fileref="refdbmanualfig1"></graphic> + <graphic fileref="refdbmanualfig1"> </figure> <para>Optionally you may use an internal database engine instead of the external SQL server, resulting in a simpler two-tier setup.</para> @@ -40,5 +40,5 @@ </listitem> <listitem> - <para>The server can run as a daemon in a non-privileged account if security concerns require this. Besides, users can start it as a standalone application on demand.</para> + <para>The server can run as a daemon in a non-privileged account if security concerns require this. Besides, users can start it as a standalone application on demand. As just about everything is configurable, a thoughtful setup will allow to run several copies of the server on the same box in parallel.</para> </listitem> <listitem> @@ -95,5 +95,5 @@ <itemizedlist> <listitem> - <para>Bibliographic output for DocBook works with both the SGML and XML version of the DTD. The DocBook output is sufficiently structured to allow transformation into other SGML or XML document types (this is in fact the way how the TEI bibliographies are created currently). DocBook SGML and XML documents can be transformed with DSSSL stylesheets which act as driver files for the well-known modular stylesheets by Norm Walsh. DocBook XML documents can also be transformed with XSL stylesheets which again are driver files for the corresponding stylesheets by Norm Walsh.</para> + <para>Bibliographic output for DocBook works with both the SGML and XML version of the DTD. The DocBook output is sufficiently structured to allow transformation into other SGML or XML document types (this is in fact the way how the TEI bibliographies are created currently). DocBook SGML and XML documents can be transformed with DSSSL and XSL stylesheets, respectively, which act as driver files for the well-known modular stylesheets by Norm Walsh.</para> <para>The TEI camp has apparently completely switched from SGML to XML, so RefDB supports only XML documents and transformation with XSL stylesheets.</para> </listitem> Index: refdb-manual-chapter10.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter10.sgml,v retrieving revision 1.19 retrieving revision 1.19.2.1 diff -u -U2 -r1.19 -r1.19.2.1 --- refdb-manual-chapter10.sgml 8 Feb 2004 00:32:45 -0000 1.19 +++ refdb-manual-chapter10.sgml 14 Nov 2004 16:04:49 -0000 1.19.2.1 @@ -84,5 +84,5 @@ <para>Use the <option>-d</option> option to specify the database that you want to work with. In an interactive session you can also set and change the default database with the <link linkend="app-c-command-selectdb"><command>selectdb</command> command</link>.</para> <para>The <option>-F</option> option specifies the default fields that are to be displayed in a <link linkend="app-c-command-getref"><command moreinfo="none">getref</command></link> query.</para> - <para>The <option>-g</option> option can be used to add some default fields to all references that are added or updated. The argument <replaceable>deffile</replaceable> is the filename of a <link linkend="sect1-ris-format">RIS file</link> containing these additional fields. &appname;c first tries the filename as is, so it should be a valid relative or absolute path. If the file is not found, &appname; looks for the file in <filename><envar>$HOME</envar>/</filename>. The command aborts if the file cannot be found.</para> + <para>The <option>-g</option> option can be used to add some default fields to all references that are added or updated. The argument <replaceable>deffile</replaceable> is the filename of a <link linkend="sect1-ris-format">RIS file</link> containing these additional fields. &appname;c first tries the filename as is, so it should be a valid relative or absolute path. If the file is not found, &appname; looks for the file in <envar>$HOME</envar>. The command aborts if the file cannot be found.</para> <para>Use the <option>-G</option> option to specify the URL of a Cascading Style Sheets (CSS) file. This file will be used to customize the HTML output of the <link linkend="app-c-command-getref"><command>getref</command></link> command. The URL can be either a local path (e.g. <filename>refdb.css</filename>, <filename>/home/myname/custom.css</filename>) or the web address of a file on a web server (e.g. <filename>http://www.mycomp.com/refdb.css</filename>).</para> <para>The <option>-R</option> option specifies the root path of your collection of electronic offprints. See the information about <link linkend="sect1-pdfroot">pdfroot</link> for further details.</para> @@ -370,5 +370,5 @@ <para>Select an input character encoding with the <option>-E</option> option if it is different from the default UTF-8. RIS datasets can use any encoding that your local libiconv supports (see <command moreinfo="none">man iconv_open</command> for a list of available encodings), except UTF-16 and UTF-32. RISX datasets carry the encoding in the processing instructions, therefore this option is ignored.</para> <para>You can use two different input file formats with this command. The default format is the <link linkend="sect1-ris-format">tagged RIS format</link>. Use <option>-t risx</option> to use XML files according to the RISX DTD as input data.</para> - <para>The <option>-g</option> option can be used in conjunction with RIS data to add some default fields to all references that are added with this command. The argument <replaceable>deffile</replaceable> is the filename of a <link linkend="sect1-ris-format">RIS file</link> containing these additional fields. &appname;c first tries the filename as is, so it should be a valid relative or absolute path. If the file is not found, &appname; looks for the file in <filename><envar>$HOME</envar>/</filename>. The command aborts if the file cannot be found.</para> + <para>The <option>-g</option> option can be used in conjunction with RIS data to add some default fields to all references that are added with this command. The argument <replaceable>deffile</replaceable> is the filename of a <link linkend="sect1-ris-format">RIS file</link> containing these additional fields. &appname;c first tries the filename as is, so it should be a valid relative or absolute path. If the file is not found, &appname; looks for the file in <envar>$HOME</envar>. The command aborts if the file cannot be found.</para> <para>Keep in mind that this default file, just like any other RIS file, has to start with a newline and needs at least the TY and ER fields.</para> <para>The following example RIS file would switch the reprint status of all added references to <quote>ON REQUEST</quote> as of Jan 1, 2001 and let them have the type <quote>journal</quote> (please note the mandatory empty first line created by a LF):</para> @@ -1003,5 +1003,5 @@ <sect2 id="sect-getref-output-html"> <title>html</title> - <para>The html backend works just like the scrn backend, but encodes this information in a <acronym>HTML</acronym> text. This comes in handy if you would like to view the results of your queries in a web browser rather than in a terminal window. You simply use the <option>-o</option> switch to write the results of your queries to a file, reusing the same filename for each query. After each query you just have to hit the reload button of your browser to view the results of the most recent query.</para> + <para>The html backend works just like the scrn backend, but encodes this information in a <acronym>HTML</acronym> text. This comes in handy if you would like to view the results of your queries in a web browser rather than in a terminal window. This is also the easiest way to obtain fairly nice-looking printed output of your reference data. You simply use the <option>-o</option> switch to write the results of your queries to a file, reusing the same filename for each query. After each query you just have to hit the reload button of your browser to view the results of the most recent query.</para> <para>The visual appearance of the generated HTML files can be customized using CSS files. The URL of the CSS file must be specified with the &appname;c <option>-G</option> command-line option or by setting the configuration variable <varname>cssurl</varname>. The global configuration file <filename moreinfo="none">/usr/local/etc/&appname;/&appname;crc</filename> is preconfigured with a <varname>cssurl</varname> entry pointing to the default CSS file installed in <filename class="directory" moreinfo="none">/usr/local/share/&appname;/css</filename>. If you want a different appearance, it might be prudent to create a copy of this CSS file and customize it as you see fit. The following element classes can be customized. In most cases, the class name reflects the database field to be formatted:</para> <itemizedlist> @@ -1094,5 +1094,5 @@ <sect2> <title>html</title> - <para>The information returned by this backend is encoded as a HTML document. Otherwise the same applies as said for the scrn backend. See <link linkend="sect-getref-output-html">above</link> for some hints about formatting the output with a CSS file.</para> + <para>The information returned by this backend is encoded as a HTML document. Use this format to print nicely formatted notes from your web browser. Otherwise the same applies as said for the scrn backend. See <link linkend="sect-getref-output-html">above</link> for some hints about formatting the output with a CSS file.</para> </sect2> <sect2> @@ -1145,7 +1145,7 @@ </varlistentry> <varlistentry> - <term>:TI:, :T2:, :T3:</term> + <term>:TI:, :T2:, :T3:, :TA:</term> <listitem> - <para>The title of the reference, of the secondary title, and of the series title, respectively.</para> + <para>The title of the reference, of the secondary title, and of the series title, respectively. :TA: performs a search in all title levels.</para> </listitem> </varlistentry> Index: refdb-manual-chapter12.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter12.sgml,v retrieving revision 1.11 retrieving revision 1.11.2.1 diff -u -U2 -r1.11 -r1.11.2.1 --- refdb-manual-chapter12.sgml 8 Feb 2004 00:32:45 -0000 1.11 +++ refdb-manual-chapter12.sgml 14 Nov 2004 16:04:49 -0000 1.11.2.1 @@ -115,4 +115,19 @@ </sect1> <sect1> + <title>Print references</title> + <para>There are two ways to print references:</para> + <itemizedlist> + <listitem> + <para>Send the output of the <command moreinfo="none">getref</command> command to a printer:</para> + <screen format="linespecific"><prompt>&appname;c: </prompt><userinput>getref -c lpr :ID:>0</userinput></screen> + <para>You should probably be a bit more selective about the references than shown above unless you want to empty the paper tray of your printer. In any case, this command will print a list of your references in the screen output format. You can use some additional plumbing along these lines to obtain a more beautiful printer output:</para> + <screen format="linespecific"><prompt>&appname;c: </prompt><userinput>getref :ID:>0 -c 'pr -f | fmt -w 70 | lpr'</userinput></screen> + </listitem> + <listitem> + <para>The second option is to write the HTML output to a file and use your browser's print capabilities.</para> + </listitem> + </itemizedlist> + </sect1> + <sect1> <title>Use the personal reference list</title> <para>If you share your reference database with other users, the personal reference list is your tool to still have the personalized database that you want. In a way, you can eat your cake and still have it. First of all, you can limit your database search with the <option>-P</option> switch of the <link linkend="app-c-command-getref">getref</link> command to those references that you added to your personal reference list. But that's not all. With &appname;, all fields of a RIS dataset which must be the same for all users (like the title or the journal information), are common and accessible to all users. The information which is likely to differ between users (the reprint status, the availability information, and the notes), are stored separately for each user. If you later retrieve datasets, you will see your own notes for the reference, while your colleague will see his notes. All the <quote>hard</quote> bibliographic information will be the same for both of you, though.</para> @@ -252,4 +267,7 @@ <title>Viewer</title> <para>While a pager will do in many cases to view the query results, a web browser is a nice alternative. The &appname; command <link linkend="app-c-command-getref"><command moreinfo="none">getref</command></link> can generate HTML output at your request with the <option>-t html</option> option. Save the output to a file and view this file with your favourite web browser. When you run the next query, reuse the filename and hit the <guibutton>reload</guibutton> button of your browser to display the new results.</para> + <tip> + <para>A web browser is also a convenient way to print references.</para> + </tip> </sect2> </sect1> Index: refdb-manual-chapter13.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter13.sgml,v retrieving revision 1.16 retrieving revision 1.16.2.1 diff -u -U2 -r1.16 -r1.16.2.1 --- refdb-manual-chapter13.sgml 17 Feb 2004 22:14:40 -0000 1.16 +++ refdb-manual-chapter13.sgml 14 Nov 2004 16:04:49 -0000 1.16.2.1 @@ -7,9 +7,9 @@ <sect1> <title>Overview</title> - <para>The purpose of this application is to create bibliographies based on an input file which contains a list of citations conforming to the CitationList XML DTD. This input file is thus not the document that you write but rather a list of citations that is extracted from your document. In the case of LaTeX/BibTeX bibliographies, the citations are listed in the <filename>.aux</filename> file which is automatically created by the LaTeX interpreter. In the case of SGML and XML bibliographies, the citation list is extracted from your document with (Open)Jade.</para> + <para>The purpose of this application is to create bibliographies based on an input file which contains a list of citations conforming to the CitationList XML DTD. This input file is thus not the document that you write but rather a list of citations that is extracted from your document. In the case of LaTeX/BibTeX bibliographies, the citations are listed in the <filename>.aux</filename> file which is automatically created by the LaTeX interpreter. In the other cases, the citation list is extracted from your document with (Open)Jade or xsltproc for SGML and XML documents, respectively.</para> <para>Besides the bibliography data, &appname;ib creates additional files in the case of SGML and XML documents. These are style sheet driver files which can be used for subsequent document transformations. They contain a few variable definitions to adapt the formatting to the required citation and bibliography style.</para> <note> <para>While you certainly can run &appname;ib directly, it is not recommended to do so in most cases. Some output, like the style specification driver files, needs post-processing to be fully usable. For your convenience, &appname; ships with the <link linkend="sect-runbib">runbib</link> script which extracts the citation list, creates the bibliography file, and performs all necessary post-processing with a single command.</para> - <para>To make things even simpler, please have a look at the <link linkend="sect-refdbnd">&appname;nd</link> script. This script creates a skeleton SGML or XML file along with a customized <filename>Makefile</filename> which takes care of everything.</para> + <para>To make things even simpler, please have a look at the <link linkend="sect-refdbnd">&appname;nd</link> script. This script creates a skeleton SGML or XML file along with a customized <filename>Makefile</filename> which takes care of everything (except preparing coffee, that is).</para> </note> </sect1> @@ -28,4 +28,5 @@ <arg>-l <replaceable>log level</replaceable></arg> <arg>-L <replaceable>log file</replaceable></arg> + <arg choice="opt" rep="norepeat">-m</arg> <arg>-n</arg> <arg choice="opt" rep="norepeat">-N <replaceable>number</replaceable></arg> @@ -47,4 +48,5 @@ <para>Use the <option>-E</option> option to select a useful output character encoding. If this option is not used, the bibliography data will use the character encoding of the database. See <command moreinfo="none">man iconv_open</command> for a list of available encodings.</para> <para>The <option>-f stdin</option> option is a crutch to make reading data from stdin possible on platforms that do not allow automatic detection of data on stdin, like Windows/Cygwin. On other platforms, &appname;ib automatically reads data from stdin if data are available.</para> + <para>If you pass the <option>-m</option> option to &appname;ib, missing references (i.e. cited references that are not in the database) will not cause an error. Processing scripts like <link linkend="sect-runbib">runbib</link> will thus continue regardless instead of throwing in the towel.</para> <para>The <option>-n</option> option instructs &appname;ib not to create style specification files. Use this option if you are sure that a current style specification file already exists. This saves about as much computing time as you need to key in this option.</para> <para>Use the <option>-N</option> option to specify where the numbering of the references is supposed to start. The default is 1. This option comes in handy if you need to cobble together composite bibliographies or per-chapter bibliographies that still need to be numbered consecutively.</para> @@ -52,5 +54,5 @@ <para>The <option>-t</option> option selects the type of output. Use "db31" to generate DocBook SGML bibliographies, "db31x" for DocBook XML bibliographies, "teix" for TEI XML bibliographies, and "bibtex" for BibTeX bibliographies. The type of output also determines the type of style specification file, if any, that will be generated in addition to the bibliography for formatting purposes. This is only a matter of concern if you want to process a DocBook XML document with the DSSSL stylesheets: In this case you should use "db31" with this option. The SGML bibliography element is also a valid XML element, but you will get a DSSSL driver file instead of a XSL driver file when you use "db31x".</para> <note> - <para>In the current implementation, the <option>-t teix</option> option will also return a DocBook bibliography which needs to be transformed to a TEI bibliography with the <link linkend="sect-bibdb2tei"><filename>bibdb2tei.xsl</filename></link> DSSSL stylesheet.</para> + <para>In the current implementation, the <option>-t teix</option> option will also return a DocBook bibliography which needs to be transformed to a TEI bibliography with the <link linkend="sect-bibdb2tei"><filename>bibdb2tei.xsl</filename></link> stylesheet.</para> </note> <para>The purpose of all other command-line switches is explained in the section <link linkend="sect1-common-command-line-options">common command-line options</link>.</para> @@ -173,4 +175,9 @@ <entry>The character encoding for the bibliography output. If this is not specified, the data will use the same encoding as the database.</entry> </row> + <row> + <entry>ignore_missing</entry> + <entry>f</entry> + <entry>If this is set to "f", missing references (i.e. cited but not in the database) will throw an error. If set to "t", you'll get a warning but missing references will not cause &appname;ib to return an error.</entry> + </row> </tbody> </tgroup> Index: refdb-manual-chapter14.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter14.sgml,v retrieving revision 1.9 retrieving revision 1.9.2.1 diff -u -U2 -r1.9 -r1.9.2.1 --- refdb-manual-chapter14.sgml 8 Feb 2004 00:32:45 -0000 1.9 +++ refdb-manual-chapter14.sgml 14 Nov 2004 16:04:49 -0000 1.9.2.1 @@ -38,4 +38,6 @@ <arg choice="req" rep="norepeat">database</arg> <arg choice="req" rep="norepeat">style</arg> + <arg choice="opt" rep="norepeat">encoding</arg> + <arg choice="opt" rep="norepeat">css-file</arg> </cmdsynopsis> <para>The script will create two files in your current working directory:</para> @@ -52,8 +54,10 @@ <sect1 id="sect-runbib"> <title>The runbib shell script</title> - <para>This shell script is a wrapper for the bibliography client &appname;ib to simplify the creation of bibliographies. For SGML and XML documents, <command>runbib</command> first runs Jade/OpenJade to retrieve a list of citations from your source document. Then it runs <link linkend="chapter-refdbib">&appname;ib</link> to generate the bibliography as an external entity based on the extracted citation information. It will also create stylesheet driver files with the formatting information for subsequent document transformations. For BibTeX documents, <command>runbib</command> uses the information in the <filename>.aux</filename> file to retrieve a bibliography file that you can use as an input file for <command>bibtex</command>.</para> + <para>This shell script is a wrapper for the bibliography client &appname;ib to simplify the creation of bibliographies. For SGML and XML documents, <command>runbib</command> first runs <command moreinfo="none">openjade</command> or <command>xsltproc</command>, respectively, to retrieve a list of citations from your source document. Then it runs <link linkend="chapter-refdbib">&appname;ib</link> to generate the bibliography as an external entity based on the extracted citation information. It will also create stylesheet driver files with the formatting information for subsequent document transformations. For BibTeX documents, <command>runbib</command> uses the information in the <filename>.aux</filename> file to retrieve a bibliography file that you can use as an input file for <command>bibtex</command>.</para> <cmdsynopsis> <command>runbib</command> <arg>-d <replaceable>database</replaceable></arg> + <arg choice="opt" rep="norepeat">-E <replaceable>encoding</replaceable></arg> + <arg choice="opt" rep="norepeat">-G <replaceable>css-file</replaceable></arg> <arg>-h</arg> <arg rep="repeat">-i <replaceable>includevar</replaceable></arg> @@ -62,4 +66,6 @@ <arg>-S <replaceable>style</replaceable></arg> <arg>-t <replaceable>type</replaceable></arg> + <arg choice="opt" rep="norepeat">-u <replaceable>username</replaceable></arg> + <arg choice="opt" rep="norepeat">-w <replaceable>password</replaceable></arg> <arg choice="req" rep="repeat">file</arg> </cmdsynopsis> @@ -73,4 +79,16 @@ </varlistentry> <varlistentry> + <term>-E <replaceable>encoding</replaceable></term> + <listitem> + <para>Specify the character encoding that the retrieved bibliography data should use.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-G <replaceable>css-file</replaceable></term> + <listitem> + <para>Set the path or the URL of a CSS file to be used by the (x)html output</para> + </listitem> + </varlistentry> + <varlistentry> <term>-h</term> <listitem> @@ -115,5 +133,5 @@ <sect2> <title>DocBook SGML output</title> - <para>&appname;ib generates two output files in addition to the ID listing created by Jade/OpenJade. Assuming you have a source file <filename moreinfo="none">foo.sgml</filename> and use the bibliography style <filename moreinfo="none">J.Biol.Chem.</filename> you will get:</para> + <para>&appname;ib generates two output files in addition to the ID listing created by Jade/OpenJade. runbib creates another output file from these. Assuming you have a source file <filename moreinfo="none">foo.sgml</filename> and use the bibliography style <filename moreinfo="none">J.Biol.Chem.</filename> you will get:</para> <variablelist> <varlistentry> @@ -135,9 +153,15 @@ </listitem> </varlistentry> + <varlistentry> + <term><filename moreinfo="none">J.Biol.Chem.css</filename></term> + <listitem> + <para>This is a CSS file which contains formatting information used by the html output.</para> + </listitem> + </varlistentry> </variablelist> </sect2> <sect2> <title>DocBook and TEI XML output</title> - <para>&appname;ib again generates two output files as for the DocBook SGML output above, and we also count the ID listing created by Jade/OpenJade. However, runbib does a little post-processing, so you'll get one additional file in the end. Assuming you have a source file <filename moreinfo="none">foo.xml</filename> and use the bibliography style <filename moreinfo="none">J.Biol.Chem.</filename> you will get:</para> + <para>&appname;ib again generates two output files as for the DocBook SGML output above, and we also count the ID listing created by xsltproc. However, runbib does a little post-processing, so you'll get two additional files in the end. Assuming you have a source file <filename moreinfo="none">foo.xml</filename> and use the bibliography style <filename moreinfo="none">J.Biol.Chem.</filename> you will get:</para> <variablelist> <varlistentry> @@ -165,4 +189,10 @@ </listitem> </varlistentry> + <varlistentry> + <term><filename moreinfo="none">J.Biol.Chem.css</filename></term> + <listitem> + <para>This is a CSS file which contains formatting information used by the html or xhtml output.</para> + </listitem> + </varlistentry> </variablelist> </sect2> @@ -188,8 +218,8 @@ <cmdsynopsis> <command>&appname;jade</command> - <arg>-d <replaceable>stylesheet</replaceable></arg> <arg>-h</arg> <arg>-i <replaceable>variable</replaceable></arg> <arg>-p <replaceable>prefix</replaceable></arg> + <arg>-s <replaceable>stylesheet</replaceable></arg> <arg>-t <replaceable>format</replaceable></arg> <arg choice="req" rep="repeat">file</arg> @@ -198,10 +228,4 @@ <variablelist> <varlistentry> - <term>-d <replaceable>stylesheet</replaceable></term> - <listitem> - <para>Select the stylesheet with this switch. Use <quote>r</quote> to select the &appname; stylesheets (default) or <quote>d</quote> to select the plain DocBook stylesheets</para> - </listitem> - </varlistentry> - <varlistentry> <term>-h</term> <listitem> @@ -236,4 +260,8 @@ </sect2> <sect2> + <title>Resolution of public identifiers</title> + <para>Public identifiers are resolved according to the SGML catalog files specified in <envar>$SGML_CATALOG_FILES</envar>. While <command>(open)jade</command> can retrieve DTDs from the web, it is advisable to keep local copies and add <command moreinfo="none">OVERRIDE YES</command> to the top of your catalog files. This ensures that the local copies are used.</para> + </sect2> + <sect2> <title>Examples</title> <para>Here we'll use the files generated in the last example above (see <link linkend="sect-runbib">runbib</link>) and generate a nicely formatted PDF file:</para> @@ -250,7 +278,9 @@ <cmdsynopsis> <command>&appname;xml</command> - <arg>-d <replaceable>stylesheet</replaceable></arg> + <arg choice="opt" rep="norepeat">-c <replaceable>fop_config_file</replaceable></arg> + <arg>-f <replaceable>fo_processor</replaceable></arg> <arg>-h</arg> - <arg>-p <replaceable>processor</replaceable></arg> + <arg>-p <replaceable>xslt_processor</replaceable></arg> + <arg>-s <replaceable>stylesheet</replaceable></arg> <arg>-t <replaceable>format</replaceable></arg> <arg choice="req" rep="repeat">file</arg> @@ -259,10 +289,4 @@ <variablelist> <varlistentry> - <term>-d <replaceable>stylesheet</replaceable></term> - <listitem> - <para>Select the appropriate stylesheet driver file with this switch. The driver file that you want to use is one of the driver files which were generated by <link linkend="sect-runbib">runbib</link>. Use the HTML driver file for HTML output and the FO driver file for all other output. You can also use this script for non-RefDB documents. Use the values <quote>"db"</quote> and <quote>tei</quote> to select the plain DocBook and TEI XSL stylesheets, respectively.</para> - </listitem> - </varlistentry> - <varlistentry> <term>-h</term> <listitem> @@ -277,4 +301,10 @@ </varlistentry> <varlistentry> + <term>-s <replaceable>stylesheet</replaceable></term> + <listitem> + <para>Select the appropriate stylesheet driver file with this switch. The driver file that you want to use is one of the driver files which were generated by <link linkend="sect-runbib">runbib</link>. Use the HTML driver file for HTML output and the FO driver file for all other output. You can also use this script for non-RefDB documents. Use the values <quote>"db"</quote> and <quote>tei</quote> to select the plain DocBook and TEI XSL stylesheets, respectively.</para> + </listitem> + </varlistentry> + <varlistentry> <term>-t <replaceable>format</replaceable></term> <listitem> @@ -283,7 +313,56 @@ </varlistentry> </variablelist> - <note> - <para>Unless you manually tweak files, the DTD and stylesheet files reference documents found on the internet. The XSL processors will therefore complain if you do not have an active internet connection.</para> - </note> + </sect2> + <sect2 id="sect2-refdbxml-init-variables"> + <title>Configuring &appname;xml</title> + <para>Instead of using the command-line switches, &appname;xml can also be configured by means of the &appname;xmlrc configuration file. As with all &appname; configuration files, you may maintain a global copy in <filename class="directory" moreinfo="none">/usr/local/etc/refdb/</filename> and one copy per user in <envar>$HOME</envar>.</para> + <table> + <title>&appname;xmlrc</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Variable</entry> + <entry>Default</entry> + <entry>Comment</entry> + </row> + </thead> + <tbody> + <row> + <entry>xslt_processor</entry> + <entry>xsltproc</entry> + <entry>The name of the XSLT processor used to transform XML documents to html or fo files. Supported values are xsltproc (default), xalan, xt, saxon, saxon-xerces (using the xerces parser instead of the built-in parser)</entry> + </row> + <row> + <entry>xslt_classpath</entry> + <entry>/usr/share/java</entry> + <entry>Specify the directory which contains the Java classes for Java-based XSLT processors. This variable is not required if you use a non-Java processor (xsltproc).</entry> + </row> + <row> + <entry>fo_processor</entry> + <entry>fop</entry> + <entry>The name of the FO processor used to transform FO files into printable output. Supported values are fop (default), passivetex, xep, and xfor.</entry> + </row> + <row> + <entry>fo_classpath</entry> + <entry>/usr/share/java</entry> + <entry>Specify the directory which contains the Java classes for Java-based FO processors. This variable is not required if you use a non-Java processor (passivetex).</entry> + </row> + <row> + <entry>fop_config_file</entry> + <entry>(none)</entry> + <entry>The path to a custom configuration file for FOP.</entry> + </row> + <row> + <entry>outformat</entry> + <entry>html</entry> + <entry>Set the default output format. Supported values are html, xhtml, pdf, and rtf. Be aware that pdf and rtf are not supported by all FO processors.</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + <sect2> + <title>Resolution of public identifiers</title> + <para>Public identifiers can be resolved to local files if you have a working XML catalog on your system and if your XSLT processor supports XML catalogs. xalan and saxon require additional Java classes to support XML catalogs. For further information, please consult Bob Stayton's <ulink url="http://www.sagehill.net/docbookxsl/UseCatalog.html">book</ulink> about XSLT.</para> </sect2> <sect2> Index: refdb-manual-chapter15.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter15.sgml,v retrieving revision 1.9 retrieving revision 1.9.2.1 diff -u -U2 -r1.9 -r1.9.2.1 --- refdb-manual-chapter15.sgml 17 Aug 2003 16:50:46 -0000 1.9 +++ refdb-manual-chapter15.sgml 14 Nov 2004 16:04:49 -0000 1.9.2.1 @@ -50,4 +50,7 @@ <para>Appearance of name, volume, and issue number of journals (bold, underlined, italics)</para> </listitem> + <listitem> + <para>Formatting of the bibliographic listing: indentation, font sizes.</para> + </listitem> </itemizedlist> <note> @@ -59,12 +62,15 @@ <para>It is recommended to use an XML editor like Emacs/PSGML to write bibliography styles using the CiteStyle XML DTD. This ensures that most XML errors get caught while you write. After you're done, the text should be validated with a validating SGML/XML parser like nsgmls or onsgmls.</para> <para>The <sgmltag>CITESTYLE</sgmltag> element defines a bibliography style for one particular journal or publisher. You can group several styles in one file with the <sgmltag>STYLESET</sgmltag> wrapper element.</para> - <para>Each <sgmltag>CITESTYLE</sgmltag> element contains exactly three top-level elements (<xref linkend="fig-citestyleschema">). The <sgmltag>STYLENAME</sgmltag> defines the name of this style. For the sake of simplicity this could be identical with the name of the journal or publisher whose bibliography style it defines, e.g. <quote>J.Biol.Chem.</quote>. The <sgmltag>REFSTYLE</sgmltag> element contains the style definitions for the various publication types that can appear in a bibliography, like books, journals, or personal communications. A special case is the type <quote>GEN</quote> which defines a default bibliography style that is applied whenever no specific definition is available for the requested type. Although the DTD does not enforce this, it is strongly recommended to define a <quote>GEN</quote> definition for each bibliography style. Finally, the <sgmltag>CITSTYLE</sgmltag> element defines the citation style, i.e. the appearance of the citations in the main text, as well as some general properties of the bibliography.</para> + <para>Each <sgmltag>CITESTYLE</sgmltag> element contains exactly four top-level elements (<xref linkend="fig-citestyleschema">). The <sgmltag>STYLENAME</sgmltag> defines the name of this style. For the sake of simplicity this could be identical with the name of the journal or publisher whose bibliography style it defines, e.g. <quote>J.Biol.Chem.</quote> or <quote>Elsevier</quote>. The <sgmltag>REFSTYLE</sgmltag> element contains the style definitions for the various publication types that can appear in a bibliography, like books, journals, or personal communications. A special case is the type <quote>GEN</quote> which defines a default bibliography style that is applied whenever no specific definition is available for the requested type. Although the DTD does not enforce this, it is strongly recommended to define a <quote>GEN</quote> definition for each bibliography style. The <sgmltag>CITSTYLE</sgmltag> element defines the citation style, i.e. the appearance of the citations in the main text. Finally, the <sgmltag>BIBSTYLE</sgmltag> element defines the properties of the bibliographic listing.</para> <figure float="0" id="fig-citestyleschema"> <title>Schematic representation of a <sgmltag>CITESTYLE</sgmltag> element</title> - <graphic fileref="refdbmanualfig4"></graphic> + <graphic fileref="refdbmanualfig4"> </figure> <para>Each definition for a publication type in turn can contain various elements that define the sequence and rendering of authorlists, publication dates, titles, and so on. This is where the real pain in defining bibliography styles lies. All available elements can hold a <sgmltag>PRECEEDING</sgmltag> and a <sgmltag>FOLLOWING</sgmltag> element which define strings that are inserted before and after the corresponding element, respectively. This can be used to place punctuation characters or brackets wherever such a non-empty element occurs. A special element is <sgmltag>SEPARATOR</sgmltag> which usually also contains punctuation characters. This element is always inserted even if the preceeding or following element is empty.</para> <para>The <sgmltag>CITSTYLE</sgmltag> element can define three different styles for citations: <sgmltag>INTEXTDEF</sgmltag> for regular citations as well as <sgmltag>AUTHORONLY</sgmltag> and <sgmltag>YEARONLY</sgmltag> for citations that keep the authors in the flow of the text. These elements are equivalent to the definition of a publication type in the <sgmltag>REFSTYLE</sgmltag> element.</para> <para>Please peruse the separate documentation for the <ulink url="http://refdb.sourceforge.net/docs.html">CiteStyle XML DTD</ulink> for the details about the individual elements.</para> + <tip> + <para>The &appname; project also provides a tool to create citation styles interactively. The <command moreinfo="none">&appname;-ms</command> Perl script is available separately from the <ulink url="http://sourceforge.net/projects/refdb/">main project page</ulink>.</para> + </tip> </sect2> </sect1> @@ -171,8 +177,8 @@ <programlisting> <citation role="REFDB"> <co id="list1-citation"> -<xref linkend="ID1X"> <co id="list1-xref"> +<xref linkend="ID1-X"> <co id="list1-xref"> </citation> <citation role="REFDB"> -<xref linkend="LITIBP-ID2X"> <co id="list1-xref2"> +<xref linkend="LITIBP-ID2-X"> <co id="list1-xref2"> </citation> </programlisting> @@ -182,5 +188,5 @@ </callout> <callout arearefs="list1-xref"> - <para>Each <sgmltag class="element">xref</sgmltag> element specifies one bibliographic reference. The value of the <sgmltag class="attribute">linkend</sgmltag> attribute encodes which bibliographic item is referenced (in this case, the database entry with the ID 1) and how the reference should be rendered (see below). It consists of the string "ID" followed by the numerical database entry ID, and a trailing one-letter type specifier ("X" in this case). This simple form does not encode the database from which the reference is to be pulled. When generating the bibliography, you will specify a default database from which all references without an explicit database label will be taken from. This form is most convenient if all your bibliographic items are stored in one database.</para> + <para>Each <sgmltag class="element">xref</sgmltag> element specifies one bibliographic reference. The value of the <sgmltag class="attribute">linkend</sgmltag> attribute encodes which bibliographic item is referenced (in this case, the database entry with the ID 1) and how the reference should be rendered (see below). It consists of the string "ID" followed by the numerical database entry ID, and a trailing one-letter type specifier ("X" in this case), separated from the rest by a dash. This simple form does not encode the database from which the reference is to be pulled. When generating the bibliography, you will specify a default database from which all references without an explicit database label will be taken from. This form is most convenient if all your bibliographic items are stored in one database.</para> </callout> <callout arearefs="list1-xref2"> @@ -192,5 +198,5 @@ <itemizedlist> <listitem> - <para>The empty <sgmltag class="element">xref</sgmltag> elements need a closing slash as in <xref linkend="ID2X"/>.</para> + <para>The empty <sgmltag class="element">xref</sgmltag> elements need a closing slash as in <xref linkend="ID2-X"/>.</para> </listitem> <listitem> @@ -202,8 +208,8 @@ <programlisting> <seg type="REFDBCITATION" part="N" TEIform="seg"> <co id="list2-citation"> -<ptr targOrder="U" target="ID1X" TEIform="ptr"/> <co id="list2-xref"> +<ptr targOrder="U" target="ID1-X" TEIform="ptr"/> <co id="list2-xref"> </seg> <seg type="REFDBCITATION" part="N" TEIform="seg"> -<ptr targOrder="U" target="LITIBP-ID2X" TEIform="ptr"/><co id="list2-xref2"> +<ptr targOrder="U" target="LITIBP-ID2-X" TEIform="ptr"/><co id="list2-xref2"> </seg> </programlisting> @@ -267,7 +273,7 @@ <citation role="REFDB"> <xref endterm="IMTHEFIRST" linkend="ID1" role="MULTIXREF"><co id="list3-multixref"> -<xref linkend="ID1X"> <co id="list3-xref"> -<xref linkend="ID14X"> -<xref linkend="ID7X"> +<xref linkend="ID1-X"> <co id="list3-xref"> +<xref linkend="ID14-X"> +<xref linkend="ID7-X"> </citation> </programlisting> @@ -288,7 +294,7 @@ <seg type="REFDBCITATION" part="N" TEIform="seg"> <ptr type="MULTIXREF" targOrder="U" target="IMTHEFIRST" TEIform="ptr"/><co id="list4-multixref"> -<ptr targOrder="U" target="ID1X" TEIform="ptr"/> <co id="list4-xref"> -<ptr targOrder="U" target="LITIBP-ID21X" TEIform="ptr"/> -<ptr targOrder="U" target="ID5X" TEIform="ptr"/> +<ptr targOrder="U" target="ID1-X" TEIform="ptr"/> <co id="list4-xref"> +<ptr targOrder="U" target="LITIBP-ID21-X" TEIform="ptr"/> +<ptr targOrder="U" target="ID5-X" TEIform="ptr"/> </seg> </programlisting> @@ -324,5 +330,5 @@ <title>Extract the list of bibliographic references</title> <para>Use Jade or OpenJade with the <filename>citations.dsl</filename> stylesheet to create a list of the reference IDs (provide full paths as needed):</para> - <screen width="60" format="linespecific"><prompt>#~ </prompt><userinput>jade -t sgml -d citations.dsl /usr/lib/sgml/declaration/docbook-3.1.dcl foo.sgml > foo.id.xml</userinput></screen> + <screen width="60" format="linespecific"><prompt>#~ </prompt><userinput>openjade -t sgml -d citations.dsl /usr/lib/sgml/declaration/docbook-3.1.dcl foo.sgml > foo.id.xml</userinput></screen> <para>Be prepared for a long list of "missing ID" error messages. This is due to the fact that the elements with the IDs that the <sgmltag>xref</sgmltag> elements in the citations point to do not yet exist, they will be generated in the &appname; bibliography output. If you process documents with more than 200 citations, you'll have to increase the maximum error limit of Jade in order to obtain all IDs the first time. After the first complete pass (including the steps outlined below), Jade will only complain about any additional citations that you have inserted since the last run.</para> <para>The output is a simple XML file that contains the information about all <sgmltag>citation</sgmltag> and <sgmltag>xref</sgmltag> elements with their relevant attributes. It is absolutely legal to extend this file with additional citation elements to specify references which are not cited but nonetheless should appear in the bibliography.</para> @@ -330,5 +336,5 @@ <para>If you edit this intermediate XML file (that is, if you do more than just fixing the Doctype line), you should make sure that the result is still valid according to the CitationList XML DTD. &appname; uses a non-validating parser to read this file so deviations from the DTD may slip through undetected and may have undesired consequences. The intermediate XML file carries the SYSTEM identifier of the CitationList XML DTD in the document type declaration. You may have to adapt the stylesheet <filename>citations.dsl</filename> to use the correct path for your local system.</para> <para>The following command line can be used to validate the document with <application>(o)nsgmls</application> (change the path to the XML declaration as necessary):</para> - <screen width="60" format="linespecific"><prompt>~$ </prompt><userinput>nsgmls -wxml -s /usr/lib/sgml/declaration/xml.dcl foo.id.xml</userinput></screen> + <screen width="60" format="linespecific"><prompt>~$ </prompt><userinput>onsgmls -wxml -s /usr/lib/sgml/declaration/xml.dcl foo.id.xml</userinput></screen> </step> <step> @@ -361,5 +367,5 @@ <title>The &appname;nd shortcut</title> <para>Now that you know all necessary steps to process SGML and XML documents, it's about time to reveal that there is a simple shortcut if you can live with some minor restrictions. The <link linkend="sect-refdbnd">&appname;nd</link> script helps you to start new SGML or XML projects and sets up a Makefile to process your document.</para> - <para>Start the script in a clean subdirectory by typing <command moreinfo="none">&appname;nd</command>. The script will start in interactive mode and ask a couple of questions. You'll have to specify the basename of your project, the SGML or XML document type declaration you'd like to use, the top-level element, the &appname; database that holds the references which you intend to cite, and the name of the bibliography style to be used with this document. The script will then create a file <basename>.short.[sgml|xml]. The ".short" reminds you that the Makefile assumes you will be using the <link linkend="sect-short-notation">short notation</link> for citations. It will also create a Makefile which is set up to perform the necessary steps to create all sorts of available formatted output.</para> + <para>Start the script in a clean subdirectory by typing <command moreinfo="none">&appname;nd</command>. The script will start in interactive mode and ask a couple of questions. You'll have to specify the basename of your project, the SGML or XML document type declaration you'd like to use, the top-level element, the &appname; database that holds the references which you intend to cite, the name of the bibliography style to be used with this document, the character encoding, and the name of a CSS file to be used with (x)html output. The script will then create a file <basename>.short.[sgml|xml]. The ".short" reminds you that the Makefile assumes you will be using the <link linkend="sect-short-notation">short notation</link> for citations. It will also create a Makefile which is set up to perform the necessary steps to create all sorts of available formatted output.</para> <para>Once you have written your document, including a few citations and a reference to the external bibliography file as explained in the previous sections, you can use the Makefile to process your document. You may know how to use Makefiles anyway, but if not, here are the main properties:</para> <itemizedlist> @@ -379,5 +385,5 @@ <term>pdf</term> <listitem> - <para>This target generates a PDF file from your source document. PDF is a widely accepted document format with free viewers for essentially all current operating systems.</para> + <para>This target generates a PDF file from your source document. PDF is a widely accepted document format with free viewers for essentially all current operating systems. Be aware that not all FO processors (used in transforming XML documents) offer PDF output.</para> </listitem> </varlistentry> @@ -391,5 +397,5 @@ <term>rtf</term> <listitem> - <para>This target generates a Rich Text Format (RTF) file. This plain text format is sort of a word processor interchange format understood by most current word processors, including MS Word, WordPerfect, and OpenOffice/StarOffice.</para> + <para>This target generates a Rich Text Format (RTF) file. This plain text format is sort of a word processor interchange format understood by most current word processors, including MS Word, WordPerfect, and OpenOffice/StarOffice. Be aware that not all FO processors offer RTF output.</para> </listitem> </varlistentry> @@ -401,5 +407,5 @@ </varlistentry> </variablelist> - <para>The Makefile also offers a few more targets. For each of the above targets there is a corresponding '<target>dist' target which creates a <filename moreinfo="none">.tar.gz</filename> archive of the output document. The target 'all', which is also the default if you don't specify a target to <command moreinfo="none">make</command>, builds all available output formats. Accordingly, the target 'dist' creates all archives. And finally, the target 'clean' removes all intermediate files and returns your directory to the original state.</para> + <para>The Makefile also offers a few more targets. For each of the above targets there is a corresponding '<target>dist' target which creates a <filename moreinfo="none">.tar.gz</filename> archive of the output document, along with its associated CSS stylesheet if applicable. The target 'all', which is also the default if you don't specify a target to <command moreinfo="none">make</command>, builds all available output formats. Accordingly, the target 'dist' creates all archives. And finally, the target 'clean' removes all intermediate files and returns your directory to the original state.</para> <para>For example, to create a formatted PDF document <filename><basename>.pdf</filename> from your <filename moreinfo="none"><basename>.short.sgml</filename> file you'd type <command moreinfo="none">make pdf</command>. <command moreinfo="none">make</command> will first convert the short-style citations to the full style using the <command moreinfo="none">&appname;xp</command> tool. Then it will generate the bibliography and the stylesheet driver files by running <command moreinfo="none">&appname;ib</command>. Finally it will run the <command moreinfo="none">&appname;jade</command> script to create the PDF output.</para> <para>The &appname;nd-generated Makefiles should be sufficient for the average document. However, feel free to modify them in order to adapt them to specific needs. For example you can specify a different style in order to switch your output to a different citation and bibliography style. <command moreinfo="none">make</command> also allows you to override variable settings on the command line. E.g. if you want to output your document using a different bibliography style without making it the permanent default, invoke <command moreinfo="none">make</command> like this:</para> Index: refdb-manual-chapter2.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter2.sgml,v retrieving revision 1.15 retrieving revision 1.15.2.1 diff -u -U2 -r1.15 -r1.15.2.1 --- refdb-manual-chapter2.sgml 8 Feb 2004 00:32:45 -0000 1.15 +++ refdb-manual-chapter2.sgml 14 Nov 2004 16:04:49 -0000 1.15.2.1 @@ -1,3 +1,3 @@ -<!DOCTYPE CHAPTER PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ +<!DOCTYPE CHAPTER PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ <!ENTITY appname "refdb"> ]> @@ -28,5 +28,5 @@ </listitem> </itemizedlist> - <para>While this portability excludes fancy GUI bells and whistles, it makes it (most likely) possible to run &appname; on the hardware and operating system that you happen to have. Both the clients and the application server should compile on all systems with a decent C compiler like <application>gcc</application>. There should be no problems to run &appname; on heterogenous networks. For Windows users the free Cygwin tools are recommended. <ulink url="http://www.cygwin.com">Cygwin</ulink> is a POSIX layer on top of Win32 including a useful selection of the popular <ulink url="http://www.gnu.org">GNU tools</ulink>.</para> + <para>Other Unix-like operating systems may work out of the box or with a minimum amount of tweaking. While this portability excludes fancy GUI bells and whistles, it makes it (most likely) possible to run &appname; on the hardware and operating system that you happen to have. Both the clients and the application server should compile on all systems with a decent C compiler like <application>gcc</application>. There should be no problems to run &appname; on heterogenous networks. For Windows users the free Cygwin tools are recommended. <ulink url="http://www.cygwin.com">Cygwin</ulink> is a POSIX layer on top of Win32 including a useful selection of the popular <ulink url="http://www.gnu.org">GNU tools</ulink>.</para> <para>To simplify the task of porting &appname; to other operating systems the package uses <application moreinfo="none">autoconf</application> and <application moreinfo="none">automake</application>.</para> </sect1> @@ -152,5 +152,5 @@ <term>Jade/OpenJade and SP/OSP-based tools (required for DocBook SGML bibliographies, import of DocBook bibliography data)</term> <listitem> - <para>Jade is a freely available and well-proven DSSSL engine which is based on the SP parser. The Jade package contains a few more SP-based tools, e.g. the nsgmls validator and the sgmlnorm normalizer. &appname; uses Jade both to extract the IDs of the references which are cited in SGML documents and to transform SGML documents using DSSSL stylesheets. sgmlnorm is required to preprocess multipart documents using the short notation for &appname; citations. The Jade/SP package is available on <ulink url="http://www.jclark.com">James Clarks homepage</ulink>. Prebuilt binaries are available for some platforms, and it builds out of the box on quite a number of platforms. Jade has seen some further development by an independent group of programmers. These newer versions were released as OpenJade/OpenSP and are available at the <ulink url="http://www.sourceforge.net/projects/openjade/">OpenJade homepage</ulink>. Instructions to build OpenJade on Windows NT/Cygwin and precompiled binaries are available <ulink url="http://members.tripod.com/~mhoenicka/openjadesp.html">here</ulink> (official Cygwin packages of OpenJade and related tools are in preparation).</para> + <para>Jade is a freely available and well-proven DSSSL engine which is based on the SP parser. The Jade package contains a few more SP-based tools, e.g. the nsgmls validator and the sgmlnorm normalizer. &appname; uses Jade both to extract the IDs of the references which are cited in SGML documents and to transform SGML documents using DSSSL stylesheets. sgmlnorm is required to preprocess multipart documents using the short notation for &appname; citations. The Jade/SP package is available on <ulink url="http://www.jclark.com">James Clarks homepage</ulink>. Prebuilt binaries are available for some platforms, and it builds out of the box on quite a number of platforms. Jade has seen some further development by an independent group of programmers. These newer versions were released as OpenJade/OpenSP and are available at the <ulink url="http://www.sourceforge.net/projects/openjade/">OpenJade homepage</ulink>.</para> <note> <para>OpenJade has some advantages over Jade for our purposes. If it is possible to obtain or compile OpenJade on your platform, you should go for it. Both Jade and OpenJade can be installed on the same machine without conflicts. The configure script will look for both OpenJade and Jade and will use the former as the default DSSSL engine in the shell script customizations if it is available.</para> @@ -161,5 +161,5 @@ <term>XSL processor (required for DocBook and TEI XML documents)</term> <listitem> - <para>If you're working with XML documents and want to transform them using the XSL stylesheets, you'll need some sort of XSL processing machinery. Popular choices are <ulink url="http://xml.apache.org">Xalan</ulink>, <ulink url="http://saxon.sourceforge.net">Saxon</ulink>, and <ulink url="http://xmlsoft.org/XSLT">xsltproc</ulink>. The latter is checked for in the configure script and will be used as the default processor if available. The Java-based tools among these need the <ulink url="http://java.sun.com">Java Virtual Machine</ulink> installed, of course. Generating printable output seems to work best through the TeX path (see below) using the <ulink url="http://users.ox.ac.uk/~rahtz/passivetex/">PassiveTeX</ulink> macros.</para> + <para>If you're working with XML documents and want to transform them using the XSL stylesheets, you'll need some sort of XSL processing machinery. Popular choices are <ulink url="http://xml.apache.org">Xalan</ulink>, <ulink url="http://saxon.sourceforge.net">Saxon</ulink>, and <ulink url="http://xmlsoft.org/XSLT">xsltproc</ulink>. The latter is checked for in the configure script and will be used as the default processor if available. The Java-based tools among these need the <ulink url="http://java.sun.com">Java Virtual Machine</ulink> installed, of course. Generating printable output seems to work best with <ulink url="http://xml.apache.org/fop/index.html">FOP</ulink>.</para> </listitem> </varlistentry> Index: refdb-manual-chapter3.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter3.sgml,v retrieving revision 1.12 retrieving revision 1.12.2.1 diff -u -U2 -r1.12 -r1.12.2.1 --- refdb-manual-chapter3.sgml 17 Aug 2003 16:50:46 -0000 1.12 +++ refdb-manual-chapter3.sgml 14 Nov 2004 16:04:49 -0000 1.12.2.1 @@ -1,3 +1,3 @@ -<!DOCTYPE CHAPTER PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ +<!DOCTYPE CHAPTER PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ <!ENTITY appname "refdb"> ]> @@ -43,4 +43,7 @@ <listitem> <para>Cygwin currently does not support named pipes/FIFOs. &appname;d uses these to implement a child->parent messaging after the application server has forked. On Cygwin, this messaging is emulated with a temporary file. This is a bit slower (and a lot kludgier and error-prone) than a named pipe and almost certainly is a security hole.</para> + <note> + <para>As of this writing, support for named pipes appears to be implemented as an experimental feature in Cygwin. </para> + </note> </listitem> <listitem> Index: refdb-manual-chapter4.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter4.sgml,v retrieving revision 1.14 retrieving revision 1.14.2.1 diff -u -U2 -r1.14 -r1.14.2.1 --- refdb-manual-chapter4.sgml 8 Feb 2004 00:32:45 -0000 1.14 +++ refdb-manual-chapter4.sgml 14 Nov 2004 16:04:49 -0000 1.14.2.1 @@ -1,3 +1,3 @@ -<!DOCTYPE CHAPTER PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ +<!DOCTYPE CHAPTER PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ <!ENTITY appname "refdb"> ]> @@ -184,5 +184,5 @@ <title>nmed2ris</title... [truncated message content] |
