Gendoc/FunctionalFeatures

Introduction and context

This page will list the functional features needed for documentation generation along with the typical users ("actors") of these features.

It is not a roadmap and the fact that a feature appears here is does not imply that it is under development or even that it should be developed soon.

The context of this effort is that by mid 2015, PolarSys solutions like Papyrus and Capella have more traction, but a lot of people are asking for a means to generate doc from the models. Gendoc is our project for documentation generation, and we feel that there is a clear opportunity to collaborate inside PolarSys to improve the existing Gendoc tool and to gather other complementary doc generators under the Gendoc umbrella. This approach was first discussed during a teleconference on July 6th 2015.

Teleconferences

[teleconference on July 6th 2015]

Rules for this page

As indicated above, the fact that a feature is listed on this page does not imply that it is under implementation or that the project committers and contributors are working on it.

The idea here is to list Gendoc features and, for each, their typical user(s), and interested parties.

Please add features description at the end of the list, and keep this template as the very last item of the list. This is best accomplished by editing the relevant main topics, i.e., "Users" or "Features" and not the templates, i.e., "User Name" or "Feature Name".

Interested parties

• Atos
• Airbus
• Airbus Defence & Space
• Ericsson
• Obeo
• Samares Engineering
• Thales
• Zeligsoft

Users

Developper

A developper is a user that is knowledgeable of the target meta models and that is a regular eclipse user.

WordProcessor expert

A wordprocessor expert is a user that has a detailed knowledge of a word processor (style, macros, etc.) like word or openoffice but that has few knowledge of the target meta models and few to no knowledge of software development.

Final user

The final user actually generates the documentation from a model and uses the documentation

User Name

• Description of user, which could include any or all of: job title, responsibilities, education/training, tool expertise, work experience, domain expertise, etc.

Features

Reliable docx output

• Description: the gendoc system must produce a reliable docx output from a docx template and an Ecore model. The ouput must conform to docx File Format (c.f. [MS-DOCX]: Word Extensions to the Office Open XML (.docx) File Format.) and must be robust to word version changes as long as the version supports the docx format.

• Initially written by: Romain Guider - Obeo
• Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S,
• Status in Gendoc 0.5.0 : Partially implemented, depends on "reliable". A fix should bee created for Gendoc 1.0 to support current version of MS Word.
• Study to re-architecture the way to save a document to improve a long term reliability for a post-1.0 version.

Reliable odt output

• Description: the gendoc system must produce a reliable odt output from a odt template and an Ecore model. The ouput must conform to odt File Format (c.f. [OpenDocument]: Word Extensions to the Libre/Open Office Open Document (.odt) File Format.) and must be robust to open document version changes as long as the version supports the odt format.

• Initially written by: Tristan Faure - Atos
• Interested parties: Atos, Airbus
• Status in Gendoc 0.5.0 : Implemented, depends on "reliable"

Simplify the edition of templates with a less technical syntax

• Description: edition of templates must be done within word and word styling within the tempate code shoud be used to determine the styling of the generated document parts. The template language should be as simple as possible and the less possible verbose so that word experts can create simple templates. Capabilities of the template language should include, to start with,
  • injection of values in a paragraph from the target models at document generation time
  • injection of values in a table from the target models at document generation time
  • repetition of templates and value injection (both in tables and paragraphs) for lists of objects from the target models at document generation time (equivalent of the for loop)
  • selection between two templates or two templates fragments based on a condition holding on model values so that document generation can accomodate diffrerent model's patterns (equivalent of the if construct)
  • insertion of images in document from an external source (either a fixed image or an image drawn from a framework like Sirius, Papyrus or any diagram manipulation technology). Make sure that vector graphics formats are supported (especially SVG)

As more as possible, existing features of native widgets of authoring tools (like images properties, styles, ...) should be prefer to technical tags.

• Initially written by: Romain Guider - Obeo
• Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S,
• Status in Gendoc 0.5.0 : Implemented with XML and Acceleo queries. Need analysis to simplify the existing syntax.

Localized error feedback

• Description: syntax errors in templates and references to unknown meta model concepts (EClasses) and features should be reported in such a way that the localization of the error in the word template is immediate. Localization of errors must point to the word paragraph (possibly template's page and line) where it lies and provide as much detail as possible on the error so that the developper can correct errors in an efficient manner.

• Initially written by: Romain Guider - Obeo
• Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S,
• Status in Gendoc 0.5.0 : To Improve. Short term: an execution trace. Long term: the most possible precise error detection in the initial template.

Model queries

• Description: developper should be able to write simple to complex queries in the templates so that they can express complex document generation behavior (like model element filtering, string processing, etc.). A list of available queries should be provided in the authoring tool. Optionally: be able to call these queries from VB Macros.

• Initially written by: Romain Guider - Obeo
• Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S,
• Status in Gendoc 0.5.0 : Implemented

Services call in templates

• Description: developpers should be able to write services in Java and call them from templates so that they can keep the templates simple while expressing rich behavior. Developpers should also be able to write java services to capture complex behavior so that word experts can call them in templates.

• Initially written by: Romain Guider - Obeo
• Interested parties: Obeo (romain.guider@obeo.fr), Atos, Airbus, Airbus D&S,
• Status in Gendoc 0.5.0 : Implemented

Hyperlinks

• Description: It shall be possible to insert hyperlink in the template to reference future parts of documents. Example (in UML2) in a property description set an hyperlink to the the definition of the type
• Initially written by: Tristan FAURE (Atos)
• Interested parties: Atos, Airbus, Airbus D&S,
• Status in Gendoc 0.5.0 : Implemented

Command Line Interface

• Description: it shall be possible to run documentation generation using command line interface. This feature shall provide the possibility to specify a template location, variables values ...
• Initially written by: Tristan FAURE (Atos)
• Interested parties: Atos
• Status in Gendoc 0.5.0 : Implemented

Rich Text

• Description: it shall be possible to insert HTML content (or another rich text content) contained in the EMF models (for example documentation of an element) in the document.
• Initially written by: Tristan FAURE (Atos)
• Interested parties: Atos, Airbus, Airbus D&S,
• Status in Gendoc 0.5.0 : Implemented

Wizards

• Description: It shall be possible to run already defined templates contained in bundles using the graphical user interface.
• Initially written by: Tristan FAURE (Atos)
• Interested parties: Atos, Airbus, Airbus D&S,
• Status in Gendoc 0.5.0 : Implemented

Metadata and variables

• Description: It shall be possible to insert some variables and meta data in the generated document. Example of metadata : name of the generated document, time of the generation, connected user.
• Initially written by: Tristan FAURE (Atos).
• Interested parties: Atos, Airbus, Airbus D&S,
• Status in Gendoc 0.5.0 : Implemented with XML tags. Need analysis to see if we can reuse existing meta-data behaviors and UI of LO and Word.

Text with identations

• Description: it shall be possible to preserve the indentations defined in the text inserted from the EMF models (for example source code from an OCL expression) in the document.
• Initially written by: Yves BERNARD (Airbus).
• Interested parties: Airbus.
• Status in Gendoc 0.5.0 : Implemented

Re-entering fragments

• Description: Callable parts of a template (i.e. "fragments") shall have the ability to call themselves directly or indirectly.

• Initially written by: Yves BERNARD (Airbus).
• Interested parties: Airbus.

Gendoc and other Eclipse Frameworks

• Description: Gendoc should be ported to work with RMF Requirements Models to generate operational concept and specification documents, compliance summaries, traceability matrices, etc.. Ideally, gendoc should be able to work with multiple models and frameworks such as RMF, EMF, EPF et al.
• Initially written by: Mannarino Systems and Software and ISO JTC1/SC7/WG24, Ronald Houde.
• Interested parties: .

Gendoc Trace/debug mode

• Description: it shall be possible to enable a "Trace" mode that would give a lot of information concerning document generation including queries processing, context...
• Initially written by: Raphaël Faudou (Samares Engineering)
• Interested parties: Samares Engineering
• Status in Gendoc 0.5.0 :

Feature Name

• Description: this is a template to describe new features. Please add features at the end of the list, and keep this template as the very last item of the list.
• Initially written by: add the company and name of the person who added this feature description.
• Interested parties: Please add company and contact name if your company would use this feature.