protegeDocgen: Protege plugin for report generation v0.99

protegeDocgen: Protege plugin for report generation
v1.0
Attributes
Name Value
author Bertrand Grégoire
keywords protege, report, generation, open source, pdf, ontology
- Introduction
  - Docgen plugin for Protege provides a quick export of all the content of an ontology (classes, instances and documentation) in various formats (html, pdf, fo...).
  - The plugin interpretes the design form defined in Protege to determine the content and layout of the sections describing the instances: only visible slots are displayed, in the order they appear in the form (from upper left down to opposite).
  - This plugin is intended for "frames" ontologies only, it does not given any useful results with OWL ontologies, and probably never will. To generate reports from OWL ontologies you might be interested in VelociOWL.
    - VelociOWL plugin website
  - This plugin relies on the AurigaDoc framework for generating its reports. (see "Librairies" section)
  - WARNING: This plugin is under development and no warranty is provided, use it at your own risk.
    - Nevertheless, it is believed to behave well ;o) See support section in case you need some help.
- Features
  - the content of the report matches the content of the forms designed in Protege
  - images are retrieved (ImageWidget)
  - graphs are included as clickable images (GraphWidget)
  - (most) HTML tags are supported in text areas
  - easy navigation means (hypertext)
  - automatic table of content
  - layout highly configurable through CSS
  - multiple output format directly available
    - XML (source file in AurigaDoc Format)
    - Single HTML Document
    - Multiple HTML Documents (DHTML)
    - MHT (Mime multipart/related) format. Can be opened in IE
    - PDF Document
    - PostScript Document
    - Formatting Object (FO) Document
    - others easily done through AurigaDoc command line
      - Java Help Format
      - HTML Help File
      - Oracle Help For Java (OHJ)
      - RTF Document (links are broken in RTF format)
- Example
  - The (single file) HTML report of the well-known "newspaper" project is online
  - a (multiple file) html report with a foldable tree (DHTML)
  - some points are worth to mention
    - clickable Graph
    - class definition, with documentation
  - XML source file (aurigadoc)
- Download - Install
  - download plugin from SourceForge
  - extract the plugin zip file to the plugin directory of Protege
    - check for the structure of the resulting directory, the right structure is:
      Protege_Directory/plugins/lu.tudor.citi.demoisel.docgen/aurigadoc
    - Eventually configure the report author, header and footer to match your organisation/project (see "Configuration" section)
  - see the FAQ for a particular note on using JAVA1.5, if it is your case
  - run Protege and launch docgen
    - quick export
      - choose File - export to format - DocGen report
      - screenshot of Protege menu
      - This export uses the settings specified in docgen.properties in the plugin directory
      - see configuration section for more information
    - configurable export (GUI)
      - choose File - export to format - Other format (export wizard)
      - In the wizard window that pops-up choose "DocGen report", hit "Next"
      - screenshot of export wizard
      - Configure your report through the graphical interface
        
        output directory and report name (it is recommended to NOT fill in the report name, that will then be generated automatically by docgen)
        
        selection of classes to be included in the export (not implemented yet, by now ALL classes are included in the report)
        
        other options, see configuration section for more information
      - screenshot of configuration interface
      - Hit "Finish" and wait a few seconds while the reports are generated, a progress box keep you informed
      - screenshot of progress box
  - Eventually generate reports in other formats
    - others formats available from AurigaDoc include
      - Java Help Format
      - HTML Help File
      - Oracle Help For Java (OHJ)
      - RTF Document (links are broken in RTF format)
    - You can generate reports in other formats using the XML report and passing it on to aurigadoc, using a simple command line as the following .bat file that must be updated to match your Protege directory, OutputDirectory and ReportName to generate RTF report.
    - command line file for RTF generation
- Requirements
  - Docgen plugin v1.0 has been tested and works with Protege3.3.1 and most Java machines (including Java 1.4.1, Java 1.4.2 and Java 1.5.0), on both Windows (XP) and Linux (Ubuntu) systems.
    - see the FAQ for a particular note on install with JAVA1.5
  - If you have an older version of Protege (3.0, 3.1 or 3.2) you may want to use Docgen v0.99fix instead of v1.0... or update your protege installation
  - No other requirements than a running Protege installation, with some 30Mb free disk space
- Configuration
  - Report can be tailored each time you call the docgen plugin directly within the wizard dialog.
  - To make those tailoring permanent please edit the file docgen.properties before running Protege, this file can be found in the plugin directory.
  - We recommand that you adapt the configuration file to your common needs (company header, for instance), and use the graphical configuration interface for Project-specific needs (format, or content)
  - Graphs (created with the GraphWidget in Protege) are made clickable in both the HTML and DHTML exports, but not at the same time, please configure in the "makeGraphMapForDHTML" option if the "content" tab if you would like to have clickable graphs in multiple page DHTML (default) or single page HTML.
  - configurable items:
    - outputDirectory
      - docgen.outputDirectory
      - docgen.reportName
    - output format
      - boolean value that triggers the generation of a report in the given format
      - docgen.output.aurigaDocXML
      - docgen.output.html
      - docgen.output.pdf
      - docgen.output.dhtml
      - docgen.output.ps
      - docgen.output.mht
      - docgen.output.fo
    - project specific information
      - All these values must be valid html code
      - Any resource (image, script) used one of these tags must be put in the "resources" directory of docgen plugin, for being available for the report generation.
      - docgen.project.author
      - docgen.project.company
      - docgen.project.header
      - docgen.project.footer
    - localisation
      - define the titles of some sections in the report in your own language (FR is default)
      - docgen.local.slots
      - docgen.local.documentation
      - docgen.local.instances
      - docgen.local.allinstances
      - docgen.local.types
    - content
      - customize the content of the report
      - docgen.includeInstancesInReport
      - docgen.showIndirectInstancesOfClasses
      - docgen.makeGraphMapForDHTML
        
        only html OR dhtml output can have clickable graphs at the same time, select here which one it will be. (Dhtml is clickable as a default)
      - docgen.includeSystemClasses
      - docgen.includeHiddenSlot
      - docgen.showTitleOfEmpySlot
      - docgen.includePageBreaks
    - technical informations
      - include some technical or debug information in the report
      - docgen.showImportantWarningsInReport
- Author
  - Bertrand Grégoire, CRP Henri Tudor
    - CRP Henri Tudor
- What's new?
  - v1.0 (25/2/2008)
    - added option for switching between clickable graphs in DHTML or HTML export
      - docgen.makeGraphMapForDHTML
        
        only html OR dhtml output can have clickable graphs at the same time, select here which one it will be. (Dhtml is clickable as a default)
    - improved graph export to remove dependency on webprotege and log4j
  - v0.99fix (released 18/6/2007)
    - fix to run in Protege 3.2 and 3.3b
  - hosting at SourceForge (16/6/2005)
  - v0.99 (released 15/6/2005)
    - Export configuration interface added
    - RTF integration removed (for security reasons ;o)
    - command-line example added (for RTF, a.o)
    - v0.99 will become v1.0 (stable) after some more testing
    - bugs notifications are welcome
  - v0.9 (released 9/6/2005)
    - Quick export fully functionnal
    - bugs notifications are welcome
- Support
  - Carrefully read the FAQ of this document Internal Link
  - Forums (on SourceForge)
  - When reporting troubles be sure to mention any helpful information
    - the version of the plugin you use
    - the version of your java machine (it is generally displayed in the protege window, as "Protege 3.0 Build 141, JVM 1.5.0_03-b07, memory=66M, Windows 2000", for instance)
    - the operating system you use, even if this should not be a problem thanks to Java technology.
- Licence
  - The licence under which this plugin is useable has not yet been determined, will probalby be GNU-GPL. In the meanwhile, please drop a mail for commercial/development usages.
    - GNU GPL license
  - The sources can be found on sourceforge, both bundled in archive and in SVN repository.
- Libraires
  - Hints for transforming GraphWidget into clickable maps were provided by Samson Tu, and improved by Jennifer Vendetti. Thanks.
    - GraphWidget discussion on Gmane.comp.misc.ontology.protege.general
    - export image from a slot
  - This plugin uses the Aurigadoc framework to generate its reports
    - AurigaDoc
  - Dom4J librairy is used for building and manipulating the report content
    - dom4j.org
- FAQ - Known Bugs
  - Graph is not clickable in PDF format
    - This is due to my limited knowledge of PDF, any hints therefore is welcome
  - Why can't I generate directly RTF from docgen?
    - RTF generation from AurigaDoc is not working properly, hyperlinks don't work, for instance. Therefor we didn't integrate it in the plugin.
    - You can nevertheless generate RTF using a simple command line, as the following .bat file that must be updated to match your Protege directory, OutputDirectory and ReportName.
  - Docgen doesn't work under JAVA 1.5
    - Yes it does, but since some class changed in JAVA 1.5 you need to fix it. Read further, it takes a second.
    - Copy the file _xalan-2.4.1.jar (available in the plugin directory) to your java install directory:
      1) locate the directory where your java jvm is installed (something like C:\Program File\Java\jre1.5.0_11)
      2) copy the file "_xalan-2.4.1.jar" to the "lib/endorsed" subdirectory, eventually creating the directory endorsed if it did not exist before.
      
      The final path of the _xalan library in this example would be C:\Program File\Java\jre1.5.0_11\lib\endorsed\_xalan-2.4.1.jar, other installation might be like C:\Java\jdk1.5.0_11\jre\lib\endorsed\_xalan-2.4.1.jar (windows) or /usr/lib/jvm/java-1.5.0-sun/jre/lib/endorsed/_xalan-2.4.1.jar (linux)... for instance.
    - Why is there a problem?
      - Xalan-J is used in a particular way that doesn't work under java 1.5
      - error description
      - mail-archives.apache.org
  - My images (ImageWidget) are not exported in the report
    - If the image displays well in Protege form, then it should export, send me a mail!
    - Accessing to a "remote project" (with the functionnality of the same name in "File" menu) does not give you access to its resource files, ImageWidget will not work with remote access, and therefore nor with docgen.
  - Docgen does not work well with remote projects
    - Some bugs occurs when exporting a project accessed on a protege server (namely: project name is "null", images are not included")
    - Nevertheless, the text, graphs and links are OK.
    - These problems come from Protege server-client infrastructure, not from docgen plugin itself. no fix by now.
    - Ask to the administrator of the server to generate the report for you, from the original protege ontology file, this will work!
  - I can't generate a PDF report for the newspaper project
    - This is being investigated, html and dhtml nevertheless work pretty well.
    - The problem comes from the fact that multiple inheritance (that is: multiple superClasses for a same Class) is not handled well by pdf navigation bar, by now.
  - misc bugs (technical details
    - fix project name is null when accessing remote projects
    - fix revision, that alwas displays 5/2/1
    - fix multiple inheritance in pdf report
      - works well in html and dhtml, but crashes PDF generation
    - fix options not handled yet
      - includeInstances = false does not remove instances
      - includeSystemClasses = true should include system slots as well
- TODO
  - I won't add more features to this piece of software, but will gladly integrate your patches if you mail them to me, or post them en the forum, ideas for possible improvements are given below
  - additional features
    - support other widget types
      - generate InstanceTableWidget content as a table instead of a list
    - implement the selection of root classes
      - selection interface is already done, but is not used in the report generation
    - verify validity of HTML code provided by user (File and GUI)
    - verify coherence when options are combined
    - Implement missing options
    - integrate RTF generation
      - bypass change of working directory by AurigaDoc in RTF generation
  - improve CSS to handle all layout in CSS
    - remove HR and slot tables from source XML
    - set layout as div classes
- DocGen is hosted by

Name	Value
author	Bertrand Grégoire
keywords	protege, report, generation, open source, pdf, ontology