Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Gendoc/FunctionalFeatures

< Gendoc
Revision as of 11:23, 20 July 2015 by Faure.tristan.gmail.com (Talk | contribs) (Wysiwyg editing of templates in word processor)

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.

WordProcessor 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), Atos
  • Status in Gendoc 0.5.0 : Implemented, depends on "reliable"

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"

Wysiwyg editing of templates in word processor

  • 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).
  • Initially written by: Romain Guider - Obeo
  • Interested parties: Obeo (romain.guider@obeo.fr), Atos
  • Status in Gendoc 0.5.0 : Implemented

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
  • Status in Gendoc 0.5.0 : To Improve

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), Atos
  • 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
  • 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
  • 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
  • Status in Gendoc 0.5.0 : Implemented


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.

Back to the top