Overview of pxDoc

 

Download pxDoc Reference Guide in PDF and pxDoc Leaflet

pxDoc Overview

Overview

A pragmatic and powerful document generation framework

pxDoc is designed to:

  • mix manual and generated document fragments, as it is rarely possible to automatically generate 100% of a document,
  • support the Microsoft Word target (and other open xml formats in the near future),
  • fully support of your specific Word templates,
  • easily mix document keywords with Java instructions with a dedicated development language and editor,
  • ability to get any Java object as input (no need to learn complex and limited query systems to get in touch with your data),
  • ability to organize documentation templates into reusable modules,
  • ability to easily implement generation algorithms of arbitrary complexity,
  • ability to develop document generators independently of the Word templates, with variable styles,
  • ability to generate complex tables with vertical merge,
  • ability to debug document generators (breakpoints, step-by-step execution...),
  • ability to generate document of arbitrary complexity and volume.


pxDoc does not require MS Word nor other third party libraries to generate documents: e.g. documents can be generated on Linux operating systems, etc.

What pxDoc is not

No, you won't design your document generators directly in MS Word with pxDoc. Nor will you have to struggle with a complex and raw java API...

Both of these common document generation approaches have severe limitations and/or drawbacks.

Main concepts

pxDoc is a templating language dedicated to the generation of documents. There are two kinds of pxDoc components:

  • pxDocGenerators: they can be launched to generate documents
  • and pxDocModules: they can be imported by pxDocGenerators or other pxDocModules, like any java class.

Each .pxdoc file defines either a pxDocModule or a pxDocGenerator.

As you can see, pxDocModules and pxDocGenerators have a lot in common. They both deal with templates, functions and variables:

  • templates: kind of java methods dedicated to building document elements
  • functions: they map to regular java methods
  • variables: they map to class fields when defined in pxDocGenerators and pxDocModules, and to regular local variables when defined in templates and functions.

The only differences between pxDocGenerators and pxDocModules are as follows:

  • pxDocModules cannot be executed to generate documents, but pxDocGenerators are dedicated to this task.
  • pxDocModules should not import pxDocGenerators
  • pxDocGenerators must define a 'root' template, which specifies the entry point for the generator.

Since a pxDoc file can define variable and functions, a pxDoc file is very close to a regular java class with the extra-ability to provide a new kind of method: the templates.

Inside the templates, you will be able to use the 30 document-oriented keywords that make pxDoc so fun and easy.

									template myTemplate(Object model) {
										
									    // start a document
									    document {
											
									      // a table of content
									      toc
									
									      // apply style Heading1
									      #Heading1 { "My first title with pxDoc" }
											
									      "Hello " color "128,128,128" { "World" } !
									    }
									}
									

Reusable pxDocGenerators

pxDoc provides the unique ability to design reusable document generators that can be applied with any Word stylesheet at generation time.

This is possible by defining 'variable' styles in your pxDoc modules and/or generators. Define the styles you need by just giving them a name! The following snippet defines variable styles such as Title, Citation and Normal:

			pxDocGenerator MySampleGenerator 
			  styles: Normal, Title, Citation {
			     ...
			  }
			

They immediately become available for applying styles:

			// '#' followed by a style name applies 
			// the chosen style to some content:
			#Title {'My Title'}
			#Citation {'pxDoc is easy !'}

At generation time, the pxDoc generation wizard will allow users to select a Word stylesheet and to bind each variable style to a style existing in the stylesheet.

pxDoc detects only styles not tagged as hidden by Word. Sometimes, Word automatically tag some styles as hidden because they are not used.

To ensure a style is not hidden, you just need to write some dummy text using this style in the dotx file. This dummy text will not appear in the generated document

Stylesheet-Dependent pxDocGenerators

If your Word stylesheet is well known and you don't want your users to select another stylesheet, (or if you simply don't need generator reusability!), you can also use your preferred and standardized Word stylesheet directly in your pxDoc templates:

			pxDocGenerator MySampleGenerator
			  stylesheet: MyDedicatedStylesheet {
			
			}
			

You can only select a 'deployed' stylesheet. A stylesheet can be deployed with an extension point, so that it can be used by pxDoc generators/modules.

When starting a new 'pxDoc Project', the creation wizard proposes options to deploy new stylesheets for you.

Stylesheet-Dependent generators have both their drawbacks and advantages:

  • drawback: your documentation templates are dependent on your particular stylesheet and the styles it defines.
  • advantage: you don't need to care about stylesheet binding at generation time, and with automatic completion and model validation, you are sure to use the right styles!

If you don't need to make your documentation generators reusable by others on different stylesheets, making your templates dependent on your stylesheet is not a problem!

You can even change your mind later and adapt your templates so that they support variable styles. It's simple with the help of pxDoc language tooling (content-assist, validation, quick-fixes, etc.)!

pxDoc Tooling Features

Integrate your pxDoc projects with pxGen

Projects UI generation, feature/repository generation (for update-site creation), integration capabilities... Refer to dedicated section.

Content assist

pxDoc provides content assist proposal everywhere possible.

Colors
Styles
Java Content-Assist
Deployed stylesheets
Enum values

pxDoc Validation & Quickfixes

pxDoc checks the validity of your document generator, and eventually provides also quickfixes to solve them.

Java Integration

Ctrl-Shift-O

Automatic Formatting

Ctrl-Shift-F

Include external (documentation or not) dialects

External Languages integration + extensibility

Mix Manual and Generated document parts

Generating 100% of a document is not always possible, nor is it desirable.

You should eventually be able to:

  • manage complex document headers (recipients, version, history of changes, signatures...), but all of this is rarely available in a model...
  • complement/justify data with supplementary manual information that was not available in your data source

With pxDoc, you can insert new or pre-existing documents into your generated document.

			// add a pre-existing document
				var String pathToSubDocument = 'path/to/subDoc.docx'
				subDocument pathToSubDocument
				
				// include if already exists, or initialize a new doc from a template
				var String pathToNewDocument = 'path/to/newSubDoc'  + i++ + '.docx'
				subDocument pathToNewDocument fromTemplate:'templates/template_1.docx'

Actually, these 'included' documents become slaves in a master/slave document relationship. They are not physically included in the generated document and remain in their own file. They can be managed under any SCM system like any other file.

pxDoc provides Word macros to expand the included documents or save standalone documents (breaking the links to the included documents and copying their content in one transportable file.)