Difference between revisions of "Gendoc/FunctionalFeatures"

Revision as of 14:34, 17 July 2015

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].

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 Defence & Space
• Airbus Helicopters
• Ericsson
• Obeo
• Thales
• Zeligsoft

Users

Developper

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

Word expert

A word expert is a user that has a detailed knowledge of word (style, macros, etc.) 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)

Wysiwyg editing of templates in word

• 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. Capabilities of the template 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).

• Initially written by: Romain Guider - Obeo
• Interested parties: Obeo (romain.guider@obeo.fr)

Localized error feedback

• Description: syntax errors in templates and references to unknown meta model concept (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)

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.)

• Initially written by: Romain Guider - Obeo
• Interested parties: Obeo (romain.guider@obeo.fr)

Services call in templates

• Description: developper 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.

• Initially written by: Romain Guider - Obeo
• Interested parties: Obeo (romain.guider@obeo.fr)

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.