Difference between revisions of "Documentation Requirements"

From GnuCash
Jump to: navigation, search
(→‎Source Languages: Comparison of document-markup languages)
(→‎Internationalization: Other Approachs)
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
Purpose of this page is to collect the requirements, which must or should be met in case we want to change the documentation file format (source language). See [{{BugURL}}/show_bug.cgi?id=722016 Bug 722016 - We should change the Documentation file format].
 
Purpose of this page is to collect the requirements, which must or should be met in case we want to change the documentation file format (source language). See [{{BugURL}}/show_bug.cgi?id=722016 Bug 722016 - We should change the Documentation file format].
−
==Target Languages by OS or Environment==
 
−
;Linux:
 
−
:;Yelp: Docbook, Mallard (Gnome only), DITA (experimental), man, info, and HTML
 
−
:;KHelpcenter (alternative, currently unsupported):Docbook, man, info, and HTML
 
−
;Macos, WWW: HTML
 
−
;Windows: CHM (aging)
 
−
;Paper: PDF
 
−
;Several Mobiles, Tablets etc.: EPub, Mobi
 
  
−
==Other Criteria==
+
= Definitions =
−
;Semantic vs. descriptive Markup: Descriptive languages use direct formatting like <bold>, <italic>, ... while in semantic languages you mark the meaning <guilabel>, <title>, ... and the rest is done by stylesheets like XSL, CSS, .... That will lead to a more consistent appearance.
 
−
;I18N: We want also create translations in an easy way, also in non-latin writing, currently having japanese and cyrillic. How difficult is the conversion of existing translations?
 
−
;Links, indexes etc: We want to link inside and between documents, generate lists of Equations, Figures, ...
 
−
;Variables/Macros: There a many things like URLs, appname, version, which we want to define at one place and use at several others.
 
−
;Software Stability: For a project, which evolved over 2 decades this is an important criterium.
 
−
:;First and last release: There should be several years of active development. If the last release was several years ago, it can be considered "dead".
 
−
:;Major reference projects: Do they have a major community of users?
 
  
−
==Source Languages==
+
; Input Format
−
[https://en.wikipedia.org/wiki/Comparison_of_document-markup_languages Comparison of document-markup languages]
+
: The source format of the documentation files. Examples are DocBook, reStructuredText (reST) and Markdown. Contributors to the documention would be encouraged to use this format.
−
;Docbook: Semantic markup, all target languages supported by XSLTs or FOP.
+
; Output Format
 +
: Formats such as HTML, EPUB or MOBI that are produced by the documention flow.
 +
; Documentation Flow
 +
: An automated process that takes in documentation source files in a given input format and outputs processed files in various output formats.
 +
; MUST, SHOULD, MAY
 +
: As defined in [https://tools.ietf.org/html/rfc2119 RFC 2119.]
  
 +
= Output Format Support =
 +
 +
The documentation flow...
 +
;Final targets:
 +
:;1. Context sensitive Help: requires support of all important OS/desktop dependent help browsers
 +
:;2. Web display: for referencing or to use search engines
 +
:;3. Couch Reading: e-Readers and paper
 +
 +
{|
 +
!width="31%"| Requirement
 +
!width="40%"| Justification
 +
!width="13%"| DocBook Support
 +
!width="13%"| reST support
 +
|-
 +
| MUST support Yelp.
 +
| Yelp is a primary HELP view for GNOME.
 +
|
 +
|
 +
|-
 +
| SHOULD support KHelpCenter.
 +
| KHelpCenter is a primary HELP viewer for KDE.
 +
|
 +
|
 +
|-
 +
| MUST support HTML output.
 +
| Required for presentation on GnuCash website.
 +
|
 +
|
 +
|-
 +
| MUST support EPUB output.
 +
| A popular format for tablets and e-readers.
 +
|
 +
|
 +
|-
 +
| SHOULD support CHM output.
 +
|
 +
|
 +
|
 +
|-
 +
| MUST support PDF output.
 +
| Many people like to read long-form documentation in PDF.
 +
|
 +
|
 +
|}
 +
 +
= Documentation Tooling =
 +
 +
All tools used in the documentation flow...
 +
 +
{|
 +
!width="33%"| Requirement
 +
!width="39%"| Justification
 +
!width="13%"| DocBook Support
 +
!width="13%"| reST support
 +
|-
 +
| MUST have several years of active development.
 +
| Project prefers to use proven tools.
 +
|
 +
|
 +
|-
 +
| MUST have a major community of users.
 +
| Better chance for support/bug fixes in larger projects.
 +
|
 +
|
 +
|}
 +
 +
= Input Format Requirements =
 +
 +
The documentation input format...
 +
 +
{|
 +
!width="33%"| Requirement
 +
!width="39%"| Justification
 +
!width="13%"| DocBook Support
 +
!width="13%"| reST support
 +
|-
 +
| MUST support semantic markup.
 +
| More consistent appearance across output formats.
 +
|
 +
|
 +
|-
 +
| MUST support reasonable version control.
 +
| Allows maintainers to handle projects and diffs easily.
 +
|
 +
|
 +
|-
 +
| MUST support linking (cross-references) inside and between documents.
 +
| A requirement for professional documentation.
 +
|
 +
|
 +
|-
 +
| SHOULD be able to generate a List of Figures, Equations, etc.
 +
| Also required for professional documentation.
 +
|
 +
|
 +
|-
 +
| MUST support variable substitutions (also referred to as macros).
 +
| Easier maintenance.
 +
|
 +
|
 +
|}
 +
 +
= Internationalization =
 +
 +
The documentation flow...
 +
 +
{|
 +
!width="33%"| Requirement
 +
!width="39%"| Justification
 +
!width="13%"| DocBook Support
 +
!width="13%"| reST support
 +
|-
 +
| MUST support internationalization.
 +
| GnuCash has a world-wide user base.
 +
|
 +
|
 +
|-
 +
| MUST support non-latin writing.
 +
| Many GnuCash users use non-latin languages.
 +
|
 +
|
 +
|}
 +
 +
;Current state:
 +
:;it: used <tt>xml2po</tt> from [https://wiki.gnome.org/Projects/GnomeDocUtils gnome-doc-utils] to create a po file. After several years without a translator, it got frozen because it became more and more "english with italian"
 +
:;other languages: manually: Chapters (files) were copied from C and then section by section translated. Because we have many <tt>section ids</tt>, tools like KDiff3 can help while ''updating'' a translation.
 +
;Currently planned:[[Po_Based_Documentation_Translations]] by the W3C Recommendation Internationalization Tag Set (ITS) Version 2.0.
 +
:;See also: [[Improve_Localization_Process]]
 +
 +
;Other Approachs: Weblate, which is used since end of 2020 for source translation, suggests  [https://www.sphinx-doc.org/en/master/ Sphinx] for documentation. It uses [http://docutils.sourceforge.net/rst.html reStructuredText] as input.
 +
:The Linux Kernel has switched to rst. They use pandoc to convert from Docbook and I think Sphinx for processing the rst directly, and it looks to me like that would work for us too.<ref>https://lists.gnucash.org/logs/2021/02/02.html#T17:04:59</ref>
 +
:GTK is in 2021 discussing to switch from GTK-doc to [https://gitlab.gnome.org/ebassi/gi-docgen/-/milestones/1 gi-docgen] (gi: gobject-introspection) <ref>Emmanuele Bassi: [https://www.bassi.io/articles/2021/02/19/documentation-changes/ halting problem :: Documentation changes]</ref>
 +
::;Development in gtk-doc: Perl was replaced by Python;
 +
:::beside the on large projects slow Doxbook, a Markdown-Subset got supported.
 +
::;general purpose documentation tools for C and C++ libraries: [https://www.doxygen.nl/index.html Doxygen]
 +
:::[https://hotdoc.github.io/ HotDoc]
 +
:::[https://casual-effects.com/markdeep/ MarkDeep]
 
[[Category:Documentation Development]]
 
[[Category:Documentation Development]]

Latest revision as of 07:22, 4 April 2021

Purpose of this page is to collect the requirements, which must or should be met in case we want to change the documentation file format (source language). See Bug 722016 - We should change the Documentation file format.

Definitions

Input Format
The source format of the documentation files. Examples are DocBook, reStructuredText (reST) and Markdown. Contributors to the documention would be encouraged to use this format.
Output Format
Formats such as HTML, EPUB or MOBI that are produced by the documention flow.
Documentation Flow
An automated process that takes in documentation source files in a given input format and outputs processed files in various output formats.
MUST, SHOULD, MAY
As defined in RFC 2119.

Output Format Support

The documentation flow...

Final targets
1. Context sensitive Help
requires support of all important OS/desktop dependent help browsers
2. Web display
for referencing or to use search engines
3. Couch Reading
e-Readers and paper
Requirement Justification DocBook Support reST support
MUST support Yelp. Yelp is a primary HELP view for GNOME.
SHOULD support KHelpCenter. KHelpCenter is a primary HELP viewer for KDE.
MUST support HTML output. Required for presentation on GnuCash website.
MUST support EPUB output. A popular format for tablets and e-readers.
SHOULD support CHM output.
MUST support PDF output. Many people like to read long-form documentation in PDF.

Documentation Tooling

All tools used in the documentation flow...

Requirement Justification DocBook Support reST support
MUST have several years of active development. Project prefers to use proven tools.
MUST have a major community of users. Better chance for support/bug fixes in larger projects.

Input Format Requirements

The documentation input format...

Requirement Justification DocBook Support reST support
MUST support semantic markup. More consistent appearance across output formats.
MUST support reasonable version control. Allows maintainers to handle projects and diffs easily.
MUST support linking (cross-references) inside and between documents. A requirement for professional documentation.
SHOULD be able to generate a List of Figures, Equations, etc. Also required for professional documentation.
MUST support variable substitutions (also referred to as macros). Easier maintenance.

Internationalization

The documentation flow...

Requirement Justification DocBook Support reST support
MUST support internationalization. GnuCash has a world-wide user base.
MUST support non-latin writing. Many GnuCash users use non-latin languages.
Current state
it
used xml2po from gnome-doc-utils to create a po file. After several years without a translator, it got frozen because it became more and more "english with italian"
other languages
manually: Chapters (files) were copied from C and then section by section translated. Because we have many section ids, tools like KDiff3 can help while updating a translation.
Currently planned
Po_Based_Documentation_Translations by the W3C Recommendation Internationalization Tag Set (ITS) Version 2.0.
See also
Improve_Localization_Process
Other Approachs
Weblate, which is used since end of 2020 for source translation, suggests Sphinx for documentation. It uses reStructuredText as input.
The Linux Kernel has switched to rst. They use pandoc to convert from Docbook and I think Sphinx for processing the rst directly, and it looks to me like that would work for us too.[1]
GTK is in 2021 discussing to switch from GTK-doc to gi-docgen (gi: gobject-introspection) [2]
Development in gtk-doc
Perl was replaced by Python;
beside the on large projects slow Doxbook, a Markdown-Subset got supported.
general purpose documentation tools for C and C++ libraries
Doxygen
HotDoc
MarkDeep
  1. ↑ https://lists.gnucash.org/logs/2021/02/02.html#T17:04:59
  2. ↑ Emmanuele Bassi: halting problem :: Documentation changes
    3. Retrieved from "https://code.gnucash.org/wiki/index.php?title=Documentation_Requirements&oldid=18811"