Skip to content

Generating Data Dictionary Documentation

Jump to bottom
Jordan Padams edited this page Feb 17, 2021 · 1 revision

This wiki page discusses how you can go about generating PDS Common and Local Data Dictionary documentation using DocBook XML.

About PDS4 DocBook XML

The PDS4 DocBook XML file is generated by the PDS4 Local Data Dictionary Tool (LDDTool) from the content of the PDS4 Information Model (IM) ontologies. LDDTool reformats the content into the DocBook Markup Language, a semantic markup language for technical documentation (http://www.oasis-open.org/docbook/). The resulting raw XML file represents a data dictionary, or metadata repository, that includes the names, definitions, and other information about the classes and attributes defined in the IM. For human readable versions of the data dictionary, the XML file is processed into HTML, PDF, and a WebHelp format.

Generating the PDS4 DocBook XML File The PDS4 DocBook XML file is generated using the following steps.

  • Invoke LDDTool with the -D option
# Mac / Linux
./bin/lddtool -lpD PDS4_CART_IngestLDD.xml

# Windows
.\bin\lddtool.bat -lpD PDS4_CART_IngestLDD.xml

  • The DocBook formatted file is written to the ./lddtool/export/DD directory.

    • Example: PDS4_PDS_DD_1F00.xml

  • To include more than one Local Data Dictionary (LDD), simply add additional LDD file names to the list.

# Mac / Linux
./bin/lddtool -lpD PDS4_CART_IngestLDD.xml \
                   PDS4_DISP_IngestLDD.xml \
                   PDS4_GEOM_IngestLDD.xml \
                   PDS4_IMG_IngestLDD.xml …  > list.txt

# Windows
.\bin\lddtool.bat -lpD PDS4_CART_IngestLDD.xml PDS4_DISP_IngestLDD.xml PDS4_GEOM_IngestLDD.xml PDS4_IMG_IngestLDD.xml …  > list.txt

Producing the Documents (Oxygen)

Human readable versions of the PDS4 Data Dictionary can be produced using the Oxygen XML Editor (https://www.oxygenxml.com/xml_editor/xml_schema.html) using the following steps

  • Start the Oxygen XML Editor
  • Go to File -> Open to load the PDS4 DocBook XML file into the editor.
  • On the editors icon ribbon, click on the “Wrench” icon (Configuration Transformation Scenarios).
  • Check one or more document format(s).
    • DocBook HTML – Produces the PDS4 Data Dictionary in HTML format.
    • DocBook PDF – Produces the PDS4 Data Dictionary in PDF format.
    • DocBook WebHelp Classic - Produces the PDS4 Data Dictionary in a Wiki format.
  • The resulting document files are written to the output subdirectory under the directory containing the DocBook XML file. For each document format chosen, a subdirectory is then created under the output directory, for example, output/html/.

Warning: Due the large size of the DocBook XML file, the Oxygen generation of the Data Dictionary document takes significant time and memory, especially for several LDDs are submitted. If an "out of memory" error results, the maximum heap size will need to be increased. (Adjust heap memory in Options -> Preferences -> XML -> XSLT-FO-XQuery -> FO Processors).  

Producing the Documents (Pandoc - HTML only)

Human readable versions of the PDS4 Data Dictionary can be produced using Pandoc (https://pandoc.org/). This section is TBD.

Clone this wiki locally