Project

General

Profile

task #8555

Evaluate document format and management for the documentation

Added by Andreas Kohlbecker 10 months ago. Updated 8 months ago.

Status:
In Progress
Priority:
New
Category:
Documentation
Target version:
Start date:
09/19/2019
Due date:
% Done:

30%

Audience:

Description

  1. research on suitable document formats
  2. documentation within the taxeditor would be preferable (see Meeting_2019-09-07:
    • In-App_Doku im Taxeditor: (see #8555)
      • via Tooltips
      • F1 --> Eclipse RCP Helpsystem
      • Export als PDF

Eclipse Help System (InfoCenter)

Resources:

The content for the eclipse help system consists of TOC XML files in which the structure of the documentation is defined. The TOC-XML files reference the content which is written in HTML.

The help system (since 3.3) has extension points for content producers that programmatically generate help content including a table of contents, keyword index, and content pages. This can be useful when converting documentation from some other format into HTML.() --> TODO: which formats are supported?

The eclipse wiki describes techniques to write the documentation in DocBook or DITA and to transform these into the eclipse help structure of TOC-XML and HTML files. --> TODO: are there maven plugins supporting the transformation?

DocBook & DITA

Documentations created in DocBook and DITA can be modularized (http://www.sagehill.net/docbookxsl/ModularDoc.html). Books can be assembled from individual chapter files whereas chapters can be hierarchically nested at arbitrary levels. DockBook 5.0 and DITA also support the concept of topics.

WYSIWYG editors for DocBook and DITA:

See also:

DocBook

DocBook mainly because this document type uses self-descriptive names for its elements: para for a paragraph, itemizedlist of an itemized list, ....

Specific parts of a chapter can be included and repeating of the same content at various places is possible. So called xml-catalog-files map virtual to real file locations. This could for example be useful to provide the location of release/develop files.

The excellent site DocBook-Publishing provides a framework for creating and publishing DocBooks. This framework includes the option to convert odt files into DocBook xml files. The tool for this transformation, OOo2sDbk, is being developed by Eric Bellot. This however only supports the conversion in one direction.


Experimental workflows

Converting Word (docx) to DocBook

https://github.com/docbook/wiki/wiki/ConvertOtherFormatsToDocBook

ooo2dbk is also available as package in debian and derivates. The source package can be downloaded from https://launchpad.net/ubuntu/+source/ooo2dbk/2.1.0-1.1.
Processing of OpenOffice 2 files (odt) requires the ooo2dbk.odf.xsl which can be extracted from the source package. Copy this file to /usr/share/xml/ooo2dbk/task #8555: Evaluate document format and management for the documentation - EDIT Platform Etablierung - Redmine
change the files location which is configured in /etc/ooo2dbk.xml.

Potential workflow to convert docx files into modularized DocBook xml files

Tools:

  • LibreOffice Writer (Version: 6.0.7.3)
    • Extract embedded images and replace embedded images with linked images: PicExtract - 1.0

Process:

  1. Open the docx file in Writer and save as odt
  2. Open the odt file
  3. Stop "Track Changes" and Disable "Show track changes", save
  4. In the toolbar click "PicExtract" which is available once the PicExtract module is installed.
  5. The dialog will offer to create Pictures/ of the document location. We accept this setting and check both options below:
    • [x] use image/object names ...
    • [x] replace embedded
  6. The extraction process may fail at some point with the notification that the document must be saved first. If this happens save the ddt and try again. If this does not help, save the odt as DocBook xml and search the xml file for <inlinegraphic fileref="embedded: the image named after that string needs to be exported manually by saving and linking to the image via the Image Properties dialog. Now you can try again to run the extraction process. Repeat these steps until the extraction completes without warning.
  7. The final XML file needs to be post processed:
    • replace all fileref="#Pictures by fileref="Pictures to fix the boken image links
    • ....

picture566-1.png View (24.4 KB) Andreas Kohlbecker, 10/08/2019 12:56 PM

History

#1 Updated by Andreas Kohlbecker 10 months ago

  • Target version set to Planning phase 1

#2 Updated by Andreas Kohlbecker 10 months ago

  • Tags set to Meeting_2019-09-02

#3 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#4 Updated by Andreas Kohlbecker 9 months ago

  • Status changed from New to In Progress

#5 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#6 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#7 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#8 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#9 Updated by Andreas Kohlbecker 9 months ago

#10 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#11 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#12 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#13 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#14 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#15 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#16 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#17 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#18 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#19 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#20 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#21 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#22 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#23 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#24 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#25 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#26 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#27 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#28 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#29 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#30 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#31 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#32 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#33 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#34 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#35 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#36 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#37 Updated by Andreas Kohlbecker 8 months ago

  • % Done changed from 0 to 30

Also available in: Atom PDF

Add picture from clipboard (Maximum size: 40 MB)