/usr/share/doc/libbrailleutils-java-doc/developer-guide.html is in libbrailleutils-java-doc 1.2.3-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 | <html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<title></title>
</head>
<body>
<h1><a name="Introduction"></a>Introduction<a href="#Introduction"
class="section_anchor"></a></h1>
<p>The goal of this project is to provide core functionality needed to interact
with PEF-files, to provide implementations for commonly used software/hardware
related to PEF-files and to provide an easy way for others to extend the list
of implementations. </p>
<h1><a name="Main_Features"></a>Main Features<a href="#Main_Features"
class="section_anchor"></a></h1>
<p>The project contains code to: </p>
<ul>
<li>Emboss a PEF-file </li>
<li>Validate a PEF-file </li>
<li>Collect meta data about a PEF-file </li>
<li>Convert from text to a PEF-file </li>
<li>Convert from a PEF-file to text </li>
<li>Implement embossers, tables and papers </li>
</ul>
<p>Soon the following features will be included too: </p>
<ul>
<li>Split a PEF-file into one file/volume </li>
<li>Merge several PEF-files into one </li>
</ul>
<h1><a name="Design"></a>Design<a href="#Design"
class="section_anchor"></a></h1>
<p>The software should be: </p>
<ul>
<li>Small </li>
<li>Extensible </li>
<li>Platform independent </li>
<li>Independent from third party libraries </li>
<li>Informative enough to build user friendly user interfaces on </li>
<li>Runnable as a Jar-file </li>
</ul>
<p>Code written for this project must work under Java SE 5. </p>
<h2><a name="XSLT_and_XPath"></a>XSLT and XPath<a href="#XSLT_and_XPath"
class="section_anchor"></a></h2>
<p>Some operations are best handled using XSLT and XPath. Where these
technologies have been used, only the versions directly supported by Java has
been used, i.e. </p>
<ul>
<li>XSLT 1.0 </li>
<li>XPath 1.0 </li>
</ul>
<p>Note that care must be taken not to use XSLT 2.0, since it is readily
available in the coding environment. Saxon 8 is used for the validation
functionality, but should not be used elsewhere. </p>
<h2><a name="Jar_Libraries"></a>Jar Libraries<a href="#Jar_Libraries"
class="section_anchor"></a></h2>
<p>The goal to avoid using additional libraries if possible has been
successful, except in validation and testing. Therefore, in order to use the
PEF validator, the following libraries must be included in the class path: </p>
<ul>
<li>isorelax.jar </li>
<li>jing.jar </li>
<li>saxon8.jar </li>
<li>xercesImpl.jar </li>
<li>xml-apis.jar </li>
</ul>
<p>To run unit tests using Ant, "junit-4.4.jar" must be in the class path. </p>
<p><i>If validation is not needed, no jar-files have to be included in the
distribution.</i> </p>
<h2><a name="Javadoc"></a>Javadoc<a href="#Javadoc"
class="section_anchor"></a></h2>
<p>An online version of the Javadoc is available <a
href="http://files.pef-format.org/javadoc/brailleUtils-1.1.0/index.html"
rel="nofollow">here</a> (release 1.1.0). </p>
<h2><a name="Services_API"></a>Services API<a href="#Services_API"
class="section_anchor"></a></h2>
<p>Java Services API is used for discovering implementations at runtime. The
reason for using this technology instead of, for example, OSGi, is because the
Services API is part of the JRE. </p>
<p>All services that an implementation wants to provide as Java services must
be published in the <tt>META-INF/services</tt> folder. That folder should
contain one file for each interface having implementations that should be
provided as Java services. The file name must equal the interface's canonical
name. The contents of each file should be a list of canonical names of classes
implementing the interface indicated by the file name. </p>
<h3><a name="Services_Implementations"></a>Services Implementations<a
href="#Services_Implementations" class="section_anchor"></a></h3>
<p>The following interfaces have been constructed so that they can be
discovered as Java services: </p>
<ul>
<li>org.daisy.braille.embosser.EmbosserProvider </li>
<li>org.daisy.braille.embosser.EmbosserCatalog </li>
<li>org.daisy.braille.table.TableProvider </li>
<li>org.daisy.braille.table.TableCatalog </li>
<li>org.daisy.paper.PaperProvider </li>
<li>org.daisy.paper.PaperCatalog </li>
<li>org.daisy.validator.Validator </li>
</ul>
<p>All of these <i>may</i> be discovered by the Services API. However, in most
cases, one of the following interfaces will provide a starting point for a
developer who wishes to add functionality to the software: </p>
<ul>
<li>org.daisy.braille.embosser.EmbosserProvider </li>
<li>org.daisy.braille.table.TableProvider </li>
<li>org.daisy.paper.PaperProvider </li>
</ul>
<h2><a name="Factory_Classes"></a>Factory Classes<a href="#Factory_Classes"
class="section_anchor"></a></h2>
<p>The classes in the org.daisy.factory package provides the foundation for the
interfaces used elsewhere in the software to discover and create objects. At
the top level is the <tt>Provider</tt> interface. Its sole purpose is to
provide a collection of factories. The factories implement the <tt>Factory</tt>
interface. </p>
<p><i>Note that the objects created using a <tt>Factory</tt> implementation are
not controlled by these interfaces.</i> </p>
<p>Different factories creating the same type of objects can be combined in a
<tt>FactoryCatalog</tt>. The catalog can then be used to extract a list of all
factories that can be used to create a specific type of objects. </p>
<h1><a name="Repository_Layout"></a>Repository Layout<a
href="#Repository_Layout" class="section_anchor"></a></h1>
<p>The trunk, tags, and branches directories live in the root directory of the
repository, and the projects are placed in subdirectories beneath those. The
main project (Braille Utils) is located in the "braille" subdirectory (<a
href="https://brailleutils.googlecode.com/svn/trunk/braille"
rel="nofollow">https://brailleutils.googlecode.com/svn/trunk/braille</a>).
Additional projects may be added to the repository in the future. </p>
<h2><a name="Braille_Utils_SVN_Layout"></a>Braille Utils SVN Layout<a
href="#Braille_Utils_SVN_Layout" class="section_anchor"></a></h2>
<p>The project contains three source folders: </p>
<ul>
<li>src </li>
<li>catalog </li>
<li>tests </li>
</ul>
<p>Core functionality should be placed in the <tt>src</tt> folder. Interface
implementations, such as embossers or papers, should generally be placed in the
<tt>catalog</tt> folder. </p>
<p>Unit tests should be placed in the <tt>tests</tt> folder, mirroring the
structure of the other two source folders. The risk for naming conflicts in the
<tt>tests</tt> folder have been minimized by using different naming schemes for
<tt>src</tt> and <tt>catalog</tt>. </p>
<h3><a name="Catalog_Layout"></a>Catalog Layout<a href="#Catalog_Layout"
class="section_anchor"></a></h3>
<p>The <tt>catalog</tt> folder has a relatively flat structure. Each folder in
the <tt>catalog</tt> folder should contain <i>related implementation
entities</i>. Each entity should be modelled on the domain of an organization
using a two-part underscore separated string where the first part begins with
the top level domain name of the organization and then the organization's
domain. If possible, use the organization of the provider of the hardware (or
software) that the implementations target. If this is not possible, use the
organization of the provider of the implementations (your organization). </p>
<p>Note that this does not imply ownership or responsibility for the code in
the package, but merely serves as identification and a structuring aid. </p>
<p>The classes in each of these folders should be considered package specific.
Implementations may not rely on other packages in the catalog. If a
functionality can be regarded as <i>generic</i>, it should be placed in the
<tt>src</tt> folder instead. </p>
<h1><a name="Testing"></a>Testing<a href="#Testing"
class="section_anchor"></a></h1>
<p>Unit tests can performed by running "build.xml" with Ant. </p>
<h1><a name="Committing_code"></a>Committing code<a href="#Committing_code"
class="section_anchor"></a></h1>
<p>If applicable, add unit tests to verify your changes and make sure that all
unit tests pass before committing code to the project. Also, remember to enter
a descriptive commit comment, describing the key aspects of your work. </p>
<h1><a name="Building_the_Project"></a>Building the Project<a
href="#Building_the_Project" class="section_anchor"></a></h1>
<p>The distribution is built by running "build.xml" with Ant. "build.xml" can
also generate Javadoc and run unit tests. All files related to this process
should be placed in the "ant-build" folder. Files created as a result of
running "build.xml" should be placed in "ant-build/output" and should not be
added to the repository. </p>
<h2><a name="Publishing_the_Project_Build"></a>Publishing the Project Build<a
href="#Publishing_the_Project_Build" class="section_anchor"></a></h2>
<p>... </p>
</body>
</html>
|