| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "https://www.w3.org/TR/html4/loose.dtd"> |
| |
| |
| <!-- ====================================================================== --> |
| <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! --> |
| <!-- ====================================================================== --> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/> |
| <style type="text/css">@import "stylesheets/base.css";</style> |
| <meta name="author" value=" |
| Apache UIMA Documentation Team"> |
| <meta name="email" value="dev@uima.apache.org"> |
| |
| |
| |
| <title>Apache UIMA - Using Docbook for documentation</title> |
| |
| <!-- Begin Cookie Consent plugin by Silktide - https://silktide.com/cookieconsent --> |
| <!-- Commented out because implied consent is not compatible with GDPR --> |
| <!-- |
| <script type="text/javascript"> |
| window.cookieconsent_options = {"message":"This website uses cookies to ensure you get the best experience on our website","dismiss":"Got it!","learnMore":"More info","link":"https://uima.apache.org/privacy-policy.html","theme":"dark-bottom"}; |
| </script> |
| |
| <script type="text/javascript" src="/cookieconsent2/cookieconsent.min.js"></script> |
| --> |
| <!-- End Cookie Consent plugin --> |
| |
| <!-- Begin Google Analytics --> |
| <!-- Commented out because GA requires consent according to GDPR --> |
| <!-- |
| <script> |
| (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-70846351-1', 'auto'); |
| ga('set', 'anonymizeIp', true); |
| ga('send', 'pageview'); |
| |
| </script> |
| --> |
| <!-- End Google Analytics --> |
| </head> |
| |
| <body> |
| <div class="topLogos"> |
| <table border="0" width="100%" cellspacing="0"> |
| <!-- TOP IMAGE --> |
| <tr> |
| <td align='LEFT'> |
| <a href="index.html"> |
| <img style="border: 1px solid black;" src="./images/UIMA_banner2tlpTm.png" alt="UIMA project logo" border="0"/> |
| </a> |
| </td> |
| <td align='CENTER'> |
| <div class="pageBanner">Using Docbook for documentation</div> |
| </td> |
| <td align='RIGHT'> |
| <a href="https://www.apache.org"> |
| <img src="./images/asf-logo-on-white-smallTm.png" alt="Apache UIMA" border="0"/> |
| </a> |
| </td> |
| </tr> |
| </table> |
| <hr noshade="" size="1"/> |
| </div> |
| <table border="0" width="100%" cellspacing="4"> |
| <tr> |
| <td align='RIGHT' colspan="2"> |
| <form method="get" action="https://www.google.com/search"> |
| Search the site |
| <input type="text" name="q" size="25" maxlength="255" value="" /> |
| <input type="hidden" name="sitesearch" value="https://uima.apache.org/" /> |
| <input name="Search" value="Search Site" type="submit"/> |
| </form> |
| </td> |
| </tr> |
| <tr> <!-- LEFT SIDE NAVIGATION --> |
| <td width="20%" valign="top"> |
| |
| |
| |
| |
| |
| |
| <!-- regular menu --> |
| <div class="navBar"> |
| <br/> |
| <div class="navBarItem"> <div class="navPartHeading">General</div> |
| </div> |
| <div class="navBar"> |
| <div class="navBarItem"> <a href="./index.html">Home</a> |
| </div> |
| <div class="navBarItem"> <a href="./downloads.cgi">Downloads</a> |
| </div> |
| <div class="navBarItem"> <a href="./documentation.html">Documentation</a> |
| </div> |
| <div class="navBarItem"> <a href="./news.html">News</a> |
| </div> |
| <div class="navBarItem"> <a href="./publications.html">Publications</a> |
| </div> |
| <br style="line-height: .5em"/> |
| <div class="navBarItem"> <a href="https://issues.apache.org/jira/browse/uima" target="_blank" rel="noopener">Issue tracker <img src="images/offsitelink.png"/></a> |
| </div> |
| <div class="navBarItem"> <a href="https://cwiki.apache.org/confluence/display/UIMA/" target="_blank" rel="noopener">Wiki <img src="images/offsitelink.png"/></a> |
| </div> |
| <br style="line-height: .5em"/> |
| <div class="navBarItem"> <a href="https://cwiki.apache.org/confluence/display/UIMA/Powered+by+Apache+UIMA" target="_blank" rel="noopener">Powered By UIMA <img src="images/offsitelink.png"/></a> |
| </div> |
| </div> |
| <br/> |
| <div class="navBarItem"> <div class="navPartHeading">Community</div> |
| </div> |
| <div class="navBar"> |
| <div class="navBarItem"> <a href="./get-involved.html">Get Involved</a> |
| </div> |
| <div class="navBarItem"> <a href="./mail-lists.html">Mailing Lists</a> |
| </div> |
| <div class="navBarItem"> <a href="./contribution-policy.html">Contribution Policies</a> |
| </div> |
| <div class="navBarItem"> <a href="./faq.html">FAQ</a> |
| </div> |
| <div class="navBarItem"> <a href="./project-guidelines.html">Project Guidelines</a> |
| </div> |
| </div> |
| <br/> |
| <div class="navBarItem"> <div class="navPartHeading">Scaleout Frameworks</div> |
| </div> |
| <div class="navBar"> |
| <div class="navBarItem"> <a href="./doc-uimaas-what.html">UIMA-AS</a> |
| </div> |
| <div class="navBarItem"> <a href="./doc-uimaducc-whatitam.html">UIMA-DUCC</a> |
| </div> |
| <div class="navBarItem"> <a href="./doc-uimaducc-demo.html">..Demo Page</a> |
| </div> |
| <div class="navBarItem"> <a href="http://uima-ducc-demo.apache.org:42133" target="_blank" rel="noopener">..Demo Live <img src="images/offsitelink.png"/></a> |
| </div> |
| </div> |
| <br/> |
| <div class="navBarItem"> <div class="navPartHeading">Components & Tools</div> |
| </div> |
| <div class="navBar"> |
| <div class="navBarItem"> <a href="./sandbox.html#uima-addons-annotators">Annotators</a> |
| </div> |
| <div class="navBarItem"> <a href="./toolsServers.html">Tools & Servers</a> |
| </div> |
| <div class="navBarItem"> <a href="./sandbox.html">Addons and Sandbox</a> |
| </div> |
| <div class="navBarItem"> <a href="./ruta.html">UIMA Ruta</a> |
| </div> |
| <div class="navBarItem"> <a href="./uimafit.html">uimaFIT</a> |
| </div> |
| <div class="navBarItem"> <a href="./external-resources.html">External Resources</a> |
| </div> |
| </div> |
| <br/> |
| <div class="navBarItem"> <div class="navPartHeading">Development</div> |
| </div> |
| <div class="navBar"> |
| <div class="navBarItem"> <a href="./dev-quick.html">Quick Start: building</a> |
| </div> |
| <div class="navBarItem"> <a href="./building-uima.html">Building from Source</a> |
| </div> |
| <div class="navBarItem"> <a href="./one-time-setup.html">One-time setups</a> |
| </div> |
| <div class="navBarItem"> <a href="./svn.html">Source Code</a> |
| </div> |
| <div class="navBarItem"> <a href="./release.html">Doing a UIMA release</a> |
| </div> |
| <div class="navBarItem"> <a href="https://www.apache.org/security/committers.html" target="_blank" rel="noopener">Doing a CVE (Apache) <img src="images/offsitelink.png"/></a> |
| </div> |
| <div class="navBarItem"> <a href="./eclipse-update-site.html">Eclipse Update Sites</a> |
| </div> |
| <div class="navBarItem"> <a href="./git.html">GIT</a> |
| </div> |
| <div class="navBarItem"> <a href="./codeConventions.html">Code Conventions</a> |
| </div> |
| <div class="navBarItem"> <a href="./uima-specification.html">UIMA Specification (OASIS)</a> |
| </div> |
| <div class="navBarItem"> <a href="./team-list.html">Project Team</a> |
| </div> |
| <div class="navBarItem"> <a href="./maven-design.html">Maven Use</a> |
| </div> |
| <div class="navBarItem"> <a href="./updating-website.html">Updating this Website</a> |
| </div> |
| </div> |
| <br/> |
| <div class="navBarItem"> <div class="navPartHeading">Events and Conferences</div> |
| </div> |
| <div class="navBar"> |
| <div class="navBarItem"> <a href="./coling14.html">COLING 2014</a> |
| </div> |
| <div class="navBarItem"> <a href="./gscl13.html">GSCL 2013</a> |
| </div> |
| <div class="navBarItem"> <a href="./iks09.html">IKS 2009</a> |
| </div> |
| <div class="navBarItem"> <a href="./gscl09.html">GSCL 2009</a> |
| </div> |
| <div class="navBarItem"> <a href="./lsm09.html">LSM 2009</a> |
| </div> |
| <div class="navBarItem"> <a href="./lrec08.html">LREC 2008</a> |
| </div> |
| <div class="navBarItem"> <a href="./gldv07.html">GLDV 2007</a> |
| </div> |
| </div> |
| <br/> |
| <div class="navBarItem"> <div class="navPartHeading">ASF</div> |
| </div> |
| <div class="navBar"> |
| <div class="navBarItem"> <a href="https://www.apache.org/licenses/" target="_blank" rel="noopener">License <img src="images/offsitelink.png"/></a> |
| </div> |
| <div class="navBarItem"> <a href="https://www.apache.org/foundation/thanks.html" target="_blank" rel="noopener">ASF Sponsors <img src="images/offsitelink.png"/></a> |
| </div> |
| <div class="navBarItem"> <a href="https://www.apache.org/foundation/sponsorship.html" target="_blank" rel="noopener">ASF Sponsorship <img src="images/offsitelink.png"/></a> |
| </div> |
| <div class="navBarItem"> <a href="./security_report">Security</a> |
| </div> |
| </div> |
| </div> |
| </td> |
| <td width="80%" align="left" valign="top"> |
| <div class="sectionTable"> |
| <table class="sectionTable"> |
| <tr><td> |
| <a name="Apache UIMA™ Docbook Bookshelf"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Apache UIMA™ Docbook Bookshelf</h1></a> |
| </td></tr> |
| <tr><td> |
| <blockquote class="sectionBody"> |
| <p>To facilitate cross referencing among UIMA docbooks, we ask users |
| when downloading these books to place the downloaded files in a common |
| directory, which we refer to as the UIMA bookshelf.</p> |
| <p>When this is done, the user will be able to follow cross reference |
| linkages within the downloaded books, without needing an internet |
| connection.</p> |
| </blockquote> |
| </p> |
| </td></tr> |
| </table> |
| <div class="sectionTable"> |
| <table class="sectionTable"> |
| <tr><td> |
| <a name="Docbook Conventions used"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Docbook Conventions used</h1></a> |
| </td></tr> |
| <tr><td> |
| <blockquote class="sectionBody"> |
| <p>The build tooling expects the following conventions to |
| be followed:</p> |
| <ul> |
| <li>Docbook source(s) should be put in the directory src/docbook/. The |
| existance of this directory is what causes the normal parent pom chain |
| to notice that docbook processing is needed during the build.</li> |
| <li>Currently, the docbooks are written to the 4.4 version of Docbook; |
| begin your files with the standard boilerplate (best to copy from another |
| docbook in the "set".</li> |
| <li>There is one designated file specified in project's POM as the property |
| "<bookNameRoot>" which must have as its value the name of the docbook |
| source file to process, minus the ".xml". This supports breaking large |
| docbooks into multiple parts, perhaps one per "chapter"; you have one |
| top-level docbook which xincludes the other parts. See the file |
| uima-docbook-overview-and-setup/src/docbook/overview-and-setup.xml for |
| an example of using this technique. |
| <p>The bookNameRoot name serves also as the book "name" |
| and must be unique among all the docbooks in the UIMA bookshelf.</p> |
| </li> |
| <li>The first part of the top docbook source must include the line: |
| <pre><xi:include xmlns:xi="https://www.w3.org/2001/XInclude" |
| href="../../target/docbook-shared/common_book_info.xml"/></pre> |
| This allows it to pick up the standard license, disclaimers, and copyright notices. |
| Please set the POM element <inceptionYear>; this is used in the copyright notice. |
| </li> |
| <li>Xinclude support is automatically provided by the docbkx toolchain; you do not have to set |
| XML entities for this at the top of your file.</li> |
| <li>Images to be included are by convention expected be located in a folder named |
| "images/[bookNameRoot]", which is located in the same parent directory as |
| the top docbook source file. The [bookNameRoot] is the name of the top docbook source |
| file, less the ".xml". The "extra" directory under "images" is used to separate |
| images from the different docbooks in the uima bookshelf.</li> |
| <li>Standard entities may be included, using the form: |
| <pre><!ENTITY imgroot |
| "images/insert-booknameroot-here/optional-sub-dir/"> |
| <!ENTITY % uimaents SYSTEM |
| "../../target/docbook-shared/entities.ent"> |
| %uimaents;</pre> |
| <p>The docbook-shared/entities... are common shared entities you can use; please |
| see the source for the list, located here: |
| <a href="https://svn.apache.org/repos/asf/uima/build/trunk/uima-build-resources/src/main/resources/docbook-shared/entities.ent" target="_blank">here</a>.</p></li> |
| </ul> |
| </blockquote> |
| </p> |
| </td></tr> |
| </table> |
| <div class="sectionTable"> |
| <table class="sectionTable"> |
| <tr><td> |
| <a name="Cross Referencing among UIMA Docbooks"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Cross Referencing among UIMA Docbooks</h1></a> |
| </td></tr> |
| <tr><td> |
| <blockquote class="sectionBody"> |
| <p>Docbooks support an enhanced cross-referencing among |
| docbook collections, using a link style called "olink". |
| Olinks allow cross-referencing and |
| hyperlinking among documents, using extra saved information about the |
| target document (being linked to, as contrasted with plain href style |
| links, which only have the link url). For instance, in PDFs, there's |
| extra info enabling the referring doc to say "page 123 in document abc". |
| For PDF and HTML, olinks allow the referring text to include a hyperlink |
| which includes target document's element title, and maybe a number (if it |
| has numbered items - such as our chapter / section numbers in the main |
| UIMA documentation). So you can get a link that looks like this: |
| <ul><li>see Section 1.5.1, ?Annotator Methods?</li></ul> |
| where the 1.5.1 was generated by docbook processing, and the "Annotator |
| Methods" was the title of that section.</p> |
| <p> |
| To make olinks work, each time a docbook is processed, an extra database |
| of info for that docbook is created, containing just the things needed for |
| this. This database, together with some other data about how the |
| multiple interlinking docbooks are arranged, is then |
| used when processing a docbook. |
| </p> |
| <p> |
| Olink data for all UIMA docbooks is stored in one additional project, |
| uima-docbook-olink, that has an attached artifact: a zip file of all |
| olink data. |
| </p> |
| <p> |
| This project is at the level 1-SNAPSHOT, and will stay there. |
| Because it's a snapshot, it is updated whenever it is "deployed". |
| Each docbook processing run updates that docbook's olink data. |
| Committers should deploy the snapshot to share updates of olink |
| data with others. |
| </p> |
| </blockquote> |
| </p> |
| </td></tr> |
| </table> |
| <div class="sectionTable"> |
| <table class="sectionTable"> |
| <tr><td> |
| <a name="Creating a new Docbook"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Creating a new Docbook</h1></a> |
| </td></tr> |
| <tr><td> |
| <blockquote class="sectionBody"> |
| <p> |
| <ul> |
| <li>Add a src/docbook directory, and put an images directory there |
| for new images (if you have images), and one or more XML files containing docbook source.</li> |
| <li>Put the name of the top docbook xml file in the project's docbookNameRoot property</li> |
| <li>Add this docbook to the UIMA bookshelf - modifying the uima-docbook-olink project's |
| src/main/docbook-olink/{html, htmlsingle, and pdf}/site.xml files. |
| <ul><li>Add a stanza to the site-map, and</li> |
| <li>add an entity for the docbookNameRoot at the top of the site file.</li> |
| </ul> |
| </li> |
| </ul> |
| </p> |
| </blockquote> |
| </p> |
| </td></tr> |
| </table> |
| </td> |
| </tr> |
| <!-- FOOTER --> |
| <tr><td colspan="2"> |
| <hr noshade="" size="1"/> |
| </td></tr> |
| <tr><td colspan="2"> |
| <table class="pageFooter"> |
| <tr> |
| <td><a href="index.html">Home</a></td> |
| <td><a href="privacy-policy.html">Privacy Policy</a></td> |
| <td style="font-size:75%"> |
| Copyright © 2006-2013, The Apache Software Foundation.<br/> |
| Apache UIMA, UIMA, the Apache UIMA logo and the Apache Feather logo are trademarks of The Apache Software Foundation.<br/> |
| All other marks mentioned may be trademarks or registered trademarks of their respective owners. |
| </td> |
| <td><a href="mailto:dev@uima.apache.org">Contact us</a></td> |
| </tr> |
| </table> |
| </td></tr> |
| </table> |
| </body> |
| </html> |
| |
