Synopsis

vocdoc creates simple latex and html documentation for a given OWL ontology file. At the moment, the assumption is that the source file is encoded in Turtle syntax.

Examples

To create latex documentation (a class and a properties file) for "ontology.n3" in "destination/folder/path":

  ruby vocdoc.rb --latex ontology.n3 destination/folder/path

To create html documentation (one large html file) in the current directory

  ruby vocdoc.rb --html ontology.n3

Usage

 ruby vocdoc.rb [options] source_file target_folder

The default for target_folder is the current folder

For help use: vocdoc.rb -h

Options

  -h, --help          Displays help message
  -v, --version       Display the version, then exit
  -q, --quiet         Output as little as possible, overrides verbose
  -V, --verbose       Verbose output
  --latex             output latex source into target folder, spread into "classes.tex"
                        and "properties.tex". This is the default.
  --html              output html source ("ontology.html") into target folder

Author

Knud Hinnerk Möller, knud.moeller@deri.org

Copyright

Configuration File

vocdoc will try to read configuration from a file "owl_doc.conf", which consists of simple attribute value pairs. The following attributes can be defined:

ontology_namespace: The namespace of the ontology for which documentation is created
doc_root: The root directory of where the documentation and ontology are located
alphabetise: defines whether or not the term lists in the documentation should be alphabetised. Possible values are "YES" and "NO"

Adjusting the Ontology Source

vocdoc makes a lot of assumptions about how the format of ontology source when it tries to generate the documentation. This is particularly true for any kind of metadata, which does not influence the semantics of the ontology or vocabulary in any way, but which is used to come up with an informative and nice-looking documentation. Most of the metadata is currently only used in the HTML output.

An example for everything described below can be found in the SWC ontology at data.semanticweb.org/ns/swc/ontology .

Namespaces

For the metadata, I use terms from the following namespaces:

 rdfs: <http://www.w3.org/2000/01/rdf-schema#>
 owl: <http://www.w3.org/2002/07/owl#>
 dcterms: <http://purl.org/dc/terms/>
 foaf: <http://xmlns.com/foaf/0.1/>
 doap: <http://usefulinc.com/ns/doap#>
 vs: <http://www.w3.org/2003/06/sw-vocab-status/ns#>
 sioc: <http://rdfs.org/sioc/ns#>

Title and Logo

rdfs:label - to specify the name of the vocabulary, which will appear as the title and first header on the HTML document.
foaf:logo - to specify the URL of a logo image, which will be shown in the upper right corner of the HTML document.

Dates

dcterms:created - to specify the date when the vocabulary was first created. Will appear in the preamble section.
dcterms:modified - to specify the date when the vocabulary was last change. Will appear in the preamble section. I use a versioning system variable for this, e.g. $Date$ on SVN.

Versions and Revisions

doap:revision or owl:versionInfo - to specify the revision/version number of the vocabulary. Will appear in the preamble section.
sioc:earlier_version or owl:priorVersion - to specify the preceeding version of the vocabulary. Will appear in the preamble section. Note that we may be misusing owl:priorVersion - we are pointing to a previous version of the document, not the ontology namespace

Authors

dcterms:creator - to specify the authors of the vocabulary. Will appear in the preamble section. Values of must be instances of foaf:Person, which must have foaf:name, foaf:surname and foaf:homepage specified. Optionally, it is also possible to instantiate a foaf:Organization with name and homepage and say that the person is foaf:member of it. This will result in the person‘s affiliation showing up in parentheses behind their name.
dcterms:contributor - to specify other contributors to the vocabulary. Will appear in the preamble section. Works just like dcterms:creator. However, it is possible to have any kind of foaf:Agent as the value. This way, it is possible to have a group as a contributor, e.g., "members of the FooBar mailing list".

Licensing Information

you can use the property http://data.semanticweb.org/ns/misc#licenseDoc to point to a resource which contains human-readable lincensing information. The licensing information can contain any kind of HTML, as long as you wrap it as CDATA (provided that you are using rdf/xml). The following triples do the trick

 ontology misc:licenseDoc licenseDoc .
 licenseDoc rdfs:comment "This work is licensed under a Creative Commons Attribution License. ..."

General Documentation

you can add an arbitrary number of sections containing further human-readable documentation. Each section will be listed between the preamble and the class and property overview. For each section, create an RDF resource (of arbitrary type) and give it an rdfs:label (the header) and rdfs:comment (the content). Link these sections to the ontology in the desired order using the vs:userDocs property. The value of that property shoudl be a list construct with the sections in the desired order.

Term Documentation

for individual terms (classes and properties), the formal defintions from the owl and rdfs namespaces are reflected in the documentation (e.g., rdfs:subClassOf, owl:TransitiveProperty, …)
the label of the term should be defined with rdfs:label
additional human-readable documentation should be given with rdfs:comment. If the value is enclosed in a CDATA element, arbitrary HTML can be used for documentation.

Required files

pp optparse rdoc/usage ostruct date uri parseconfig rdf/redland rdf/redland/schemas/rdfs rdf/redland/schemas/owl