Changeset 13863


Ignore:
Timestamp:
2007-02-07T13:39:51+13:00 (15 years ago)
Author:
lh92
Message:

* empty log message *

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/gsdl-documentation/manuals/README.html

    r13645 r13863  
    11<html>
    22<head>
    3 <title>Greenstone Manuals</title>
     3<title>Greenstone Manuals README</title>
    44</head>
    55<body>
     
    1111<li><a href="#contents">Contents of this package</a></li>
    1212<li><a href="#file-structure">File structure</a></li>
     13<li><a href="#include-gli-help">Including GLI Help in the User Guide</a></li>
    1314<li><a href="#generate-html">Generating HTML files</a></li>
    1415<li><a href="#pdf">Generataing PDF files</a></li>
     
    3132<dl>
    3233<dt>README.html</dt><dd>This file</dd>
    33 <dt>xml-source directory</dt><dd>Contains all the XML source files and images. Any changes to the Manuals should be made to the source files in this directory. The xml-source directory contains:
    34 <ul>
    35 <li>en, es, fr, ru subdirectories, which hold the source files for English, Spanish, French and Russian respectively. Each subdirectory contains 4 XML files and an images subdirectory. The 4 XML files correspond to the 4 Greenstone manuals: Develop's manual, Installer's manual, User's manual, and From Paper to Collection manual. The images directory contains all the images for every manual.</li>
    36 <p><b>Note:</b> The en folder for English is the primary one. Any changes should be made to this folder and let the translator take care of other languages.</p>
     34<dt>xml-source directory</dt><dd>Contains all the XML source files and images.
     35Any changes to the Manuals should be made to the source files in this directory.
     36The xml-source directory contains:
     37<ul>
     38<li>en, es, fr, ru subdirectories, which hold the source files for English,
     39Spanish, French and Russian respectively. Each subdirectory contains 4 XML files
     40and an images subdirectory. The 4 XML files correspond to the 4 Greenstone
     41manuals: Develop's manual, Installer's manual, User's manual, and From Paper to
     42Collection manual. The images directory contains all the images for every
     43manual.</li>
     44<p><b>Note:</b> The en folder for English is the primary one. Any changes should
     45be made to this folder and let the translator take care of other languages.</p>
    3746<li>manual.dtd: the DTD with the XML files</li>
    3847</ul>
    3948</dd>
    40 <dt>processing directory</dt><dd>Contains all the XSL files and CSS files for running XSL transform:
    41 <ul>
     49<dt>processing directory</dt><dd>Contains all the XSL files and CSS files for
     50running XSL transform:
     51<ul>
     52<li><b>xml-to-top-index.xsl </b>XSL Transform file to generate a top index file
     53for all the manuals.</li>
     54<li><b>xml-to-index.xsl</b> XSL Transform file to generate an index file for
     55individual chapters of one manual.</li>
     56<li><b>xml-to-one-html.xsl</b> XSL transform file to generate a single HTML page
     57for each manual.</li>
     58<li><b>xml-to-many-html.xsl</b> XSL transform file to generate individual HTML
     59files for each manual, every chapter is a HTML file.</li>
    4260<li><b>common.xsl</b> Common XSL templates for use with all transforms.</li>
    43 <li><b>xml-to-one-html.xsl</b> XSL transform file to generate a single HTML page for each manual.</li>
    44 <li><b>xml-to-many-html.xsl</b> XSL transform file to generate individual HTML files for each manual, every chapter is a HTML file.</li>
    45 <li><b>xml-to-index.xsl</b> XSL Transform file to generate an index file for individual chapters of one manual.</li>
    46 <li><b>xml-to-pdf.xsl</b> XSL Transform file to generate a PDF file for every manual.</li>
     61<li><b>xml-to-pdf.xsl</b> XSL Transform file to generate a PDF file for every
     62manual.</li></a>
     63
     64<a name="contents"/>
    4765<li><b>fo-common.xsl</b> Common XSL templates for use with PDF transforms.</li>
    48 <li><b>crossref-inter.xsl, crossref.xsl, crossref-pdf.xsl</b> XSL files for getting the correct link address for links that refer to other chapters, sections, footnotes or other manuals. crossref-inter.xsl is used for generating multiple HTML files, crossref.xsl for generating a single HTML file, and crossref-pdf.xsl for generating PDF file.</li>
     66<li><b>crossref-inter.xsl, crossref.xsl, crossref-pdf.xsl</b> XSL files for
     67getting the correct link address for links that refer to other chapters,
     68sections, footnotes or other manuals. crossref-inter.xsl is used for generating
     69multiple HTML files, crossref.xsl for generating a single HTML file, and
     70crossref-pdf.xsl for generating PDF file.</li></a>
     71<li><b>manifest.xml </b>list of the manuals, used for generate the top index.</li>
     72<li><b>pdf-fonts</b> directory holds all the font files for languages whose
     73fonts are not included in the base 14 fonts that FOP supports(see
     74<a href="http://xmlgraphics.apache.org/fop/0.20.5/fonts.html">here</a>
     75for more).</li>
    4976</ul>
    5077</dd>
     
    7097    --<i>language-code</i>
    7198      --html
    72         (all the generated html files)
     99        (all the generated html files go here)
    73100      --pdf
    74         (all the generated pdf files)
     101        (all the generated pdf files go here)
    75102      --images
    76103      style.css
     104</pre>
     105
     106<a name="include-gli-help"/>
     107<h2>Including the GLI Help in User Guide</h2>
     108<p>The "Librarian Interface user guide" section in the User's Guide manual is generated from the GLI Help, so when GLI Help was updated, this section needs to be regenerated to an XML file under xml-source/language directory. To regenerate the XML file,</p>
     109<ol>
     110<li>Go to the Greenstone installation directory and run <code>source setup.bash</code></li>
     111<li>Go to the <code>gsdl-documentation/shared</code> directory, run <br/>
     112<code>java ApplyXSLT ../manuals/processing/gen-gli-help-to-manual-chapter.xsl $GSDLHOME/gli/help/{lang}/help.xml > ../manuals/xml-source/{lang}/help-{lang}.xml</code>
     113<p>replace <code>{lang}</code> with a specific language code, for example:</p>
     114<code>java ApplyXSLT ../manuals/processing/gen-gli-help-to-manual-chapter.xsl $GSDLHOME/gli/help/en/help.xml > ../manuals/xml-source/en/help-en.xml</code>
     115</li>
     116</ol>
     117<p>In the XML source file of User's Guide, GLI Help is included by means of defining an ENTITY(chap_gli) in the DTD. For example:</p>
     118<pre>
     119&lt;!DOCTYPE Manual [
     120 &lt;!ENTITY chap_gli SYSTEM "help-en.xml"&gt;
     121]&gt;
    77122</pre>
    78123
     
    95140-->
    96141</ol>
    97 <p>The generate-html.sh scripts are shell scripts that carry out a lot of these commands for you.</p>
     142<p>The generate-html.sh scripts are shell scripts that carry out a lot of these
     143commands for you, we recommend to use this script to generate the HTML pages.</p>
    98144
    99145<a name="pdf"/>
     
    104150<li>Generate the PDF file:<br/>
    105151<tt>export CLASSPATH=$CLASSPATH:../shared/fop/build/fop.jar:../shared/fop/lib</tt><br/>
    106 <tt>./../shared/fop/fop.sh -xsl processing/xml-to-pdf.xsl -xml xml-source/<i>language-code</i>/<i>manual-name</i>_<i>language-code</i>.xml -pdf build/<i>language-code</i>/pdf/<i>manual-name</i>_<i>language-code</i>.pdf</tt></li>
    107 </ol>
    108 <p>The generate-pdf.sh scripts are shell scripts that carry out a lot of these commands for you.</p>
     152<tt>./../shared/fop/fop.sh -c ../shared/fop/conf/userconfig.xml -q -xsl processing/xml-to-pdf.xsl -xml xml-source/<i>language-code</i>/<i>manual-name</i>_<i>language-code</i>.xml -pdf build/<i>language-code</i>/pdf/<i>manual-name</i>_<i>language-code</i>.pdf</tt></li>
     153</ol>
     154<p>The generate-pdf.sh scripts are shell scripts that carry out a lot of these
     155commands for you, we recommend you to use </p>
    109156
    110157<a name="status"/>
     
    128175<p>To tranlate these manuals into other languages, use Greenstone Translator to do this, see <a href="http://wesson.cs.waikato.ac.nz:7070/wiki/index.php/GTI">here</a>.</p>
    129176<p>The "module-name" for the manuals are devmanual, installmanual, papermanual and usermanual.</p>
     177<p>For languages whose fonts are not included in the base 14 fonts that FOP
     178supports, eg. Russian, new font may be required to install before generating PDF
     179files in these languages. Install a new language to FOP have 3 steps:</p>
     180<ol>
     181    <li>Find an appropriate font file (in .PFM or .TTF format) that contains the
     182    necessary fonts, and run to
     183    generate an XML file</li>
     184    <li>Register to FOP by adding a new entry in the userconfig.xml file</li>
     185    <li>In fo-common.xsl, add a new language-value pair for the <code>font</code><i>
     186    </i>variable.</li>
     187</ol>
     188
     189<p><b>[Example]</b></p>
     190<p>For example, for the Russian language, the <code>L_10646.TTF</code>(under
     191Windows) TrueType Font file contains the required Cyrillic font, then run</p>
     192<blockquote>
     193    <p><code><font size="2">java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;lib\xercesImpl.jar;lib\xalan.jar
     194    org.apache.fop.fonts.apps.TTFReader [options] L_10646.TTF Cyrillic.xml</font></code></p>
     195</blockquote>
     196<p>to generate the font xml configure file <code>Cyrillic.xml</code>.</p>
     197<p>Then go to the <code>conf</code> directory under fop installation directory,
     198open <code>userconfig.xml</code> file, in <code>&lt;fonts&gt;</code> element, add</p>
     199<blockquote>
     200    <p><code><font size="2">&lt;font metrics-file=&quot;//research/lh92/gsdl-documentation/shared/fop/conf/Cyrillic.xml&quot;
     201    kerning=&quot;yes&quot; embed-file=&quot;//research/lh92/gsdl-documentation/shared/fop/conf/L_10646.TTF&quot;&gt;<br>
     202&nbsp; &lt;font-triplet name=&quot;Cyrillic&quot; style=&quot;normal&quot; weight=&quot;normal&quot;/&gt;<br>
     203&nbsp; &lt;font-triplet name=&quot;Cyrillic&quot; style=&quot;normal&quot; weight=&quot;bold&quot;/&gt;<br>
     204&nbsp; &lt;font-triplet name=&quot;Cyrillic&quot; style=&quot;italic&quot; weight=&quot;normal&quot;/&gt;<br>
     205&nbsp; &lt;font-triplet name=&quot;Cyrillic&quot; style=&quot;italic&quot; weight=&quot;bold&quot;/&gt;<br>
     206    &lt;/font&gt;</font></code></p>
     207</blockquote>
     208<p>Then run fop with <code>-c userconfig.xml</code> option to use the new
     209configuration.</p>
    130210
    131211<a name="todo"/>
    132 <h2>Known problems and TODO list</h2>
    133 <ol>
    134 <li>Automatic texts<dd>Texts like button names should be automatic generated, like in greenstone tutorials, but currently we didn't do this because the manuals are supposed to be rewritten soon, but this shall be done after the reversion.</dd></li>
    135 <li>PDF fonts<dd>The XML to PDF transform require for a correct font set for a specific language.</dd></li>
    136 <li>Images in PDF files<dd>Sometimes when images contain unusual fonts and characters, the conversion of the XML to PDF might broke down.</dd></li>
    137 <li>Navigation buttons<dd>Add navigation buttons in the html pages.</dd></li>
     212<h2>ToDo list</h2>
     213<ol>
     214<li>Windows scripts<li>Automatic texts<p>Texts like button names should be automatic generated, like in greenstone tutorials, but currently we didn't do this because the manuals are supposed to be rewritten soon, but this shall be done after the reversion.</p></li>
     215<li>PDF fonts (done, but for new languages still needs to find an appropriate
     216font set)<p>The XML to PDF transform require for a correct font set for a
     217specific language.</p></li>
     218<li>Images in PDF files<p>Images should not be too long, otherwise cannot
     219generate the PDF file.</p></li>
     220<li>Navigation buttons (done)<p>Add navigation buttons in the html pages.</p></li>
    138221</ol>
    139222</body>
Note: See TracChangeset for help on using the changeset viewer.