Novell Home

Plug-in SDK

PLUG-IN DOCUMENTATION

The SDK includes an automatic document generation system based on LibreOffice. You will edit a simple file which describes a constrained set of information for your specific plug-in, and then during the build one or more documents will incorporate that information into templates to produce embedded help and external documentation.

Each plug-in contains a source document in the development directory under docs called release.odt. Open that file and edit each section as described in the header for that section. Follow the formatting instruction at the top of the file with respect to screenshots and headings.

Document Generation

The build process builds the documentation as follows:

  1. The template documents are copied into the /proj/content/build/<plug-in> directory.
    • plugin.odt is the template for the doc included in the plug-in itself (not all plug-in types use this)
    • external.odt is the template for the doc used externally
  2. The release documentation release.odt is copied into the same area.
  3. All docs are unzipped (ODTs are just ZIPs) and then embedded variables are replaced with information derived from the plug-in source.
    • See below for the supported variables that you can reference in your text.
  4. The documents are re-compressed, and then are opened; opening the documents will cause the release document sections to be inserted into the templates and the table of contents to be updated.
  5. The documents are then converted to PDF (you'll see the build process pause here).
  6. The documents are renamed and copied to their respective locations.
    • The plug-in doc is placed in the plug-in file; the external doc is copied to the root of the build and given the same name as the plug-in (except of course for the extension).

Document Variables

If you place these variables in your documentation, they will be replaced with the corresponding plug in-specific information derived from the source and source directory structure. If possible, it's a good idea to use these variables instead of their current settings; this ensures that if things change (say, for example, the product you are integrating with is purchased by a different vendor) then you don't need to edit your documentation to pull in the new values.

@AUTHOR@
This variable is replaced with the author of this plug-in (this is an Eclipse plug-in setting, editable via Window > Preferences > Sentinel SDK.
@PLUGIN@
This variable is replaced with the name of the plug-in, for example "Disable Identity" or "Novell Identity Manager".
@PLUGSAFE@
This variable is replaced with the "path safe" version of the plug-in name, for example "Disable-Identity" or "Novell_Identity-Manager".
@TMPLTVER@
This variable is replaced with the template version in use, for example "2011.1".
@PKGVER@
This variable is replaced with the template version and release number, for example "6.1r1"
@PLUGNAME@
This variable is replaced with the full path-safe name of the plug-in, for example "Novell_Identity-Manager_6.1r1".
@PLUGTYPE@
This variable is replaced with the type of plug-in, for example "Action", "Collector".
@RELDATE@
This variable is replaced with the current date, for example "Dec 2008".
@RELTIME@
This variable is replaced with the current time in seconds since 1970.
@UUID@
This variable is replaced with the UUID for this plug-in.
@PLUGDESC@
This variable is replaced with the description for this plug-in (from plugin.properties).

© 2014 Novell