Closed herzbube closed 4 months ago
Wikipedia has an article with a list and comparison of Lightweight Markup Languages.
LMLs not to be considered are those tied to a specific application, such as wiki markup languages, or LMLs that are not widely-used.
These are the candidates:
The drawback of Markdown is that it has many flavours. There has been an effort to standardize the format under the name "CommonMark", but so far these efforts have not resulted in a final specification.
Basic Markdown and even CommonMark lacks various features, notably there is no support for definition lists or tables. This support is then added by flavours such as GitHub Flavored Markdown, or Djot.
If Markdown is selected, then one of the flavours must be selected to support the missing features. Whether a flavour is eligible is then determined by the requirements for transforming into HTML.
reSTructuredText (reST) is used mainly by the Python community to document Python and Python libraries/programs.
There is a clean specification for reST and it is widely used. The Sphinx document generator, and by extension also the documentation hosting platform Read the Docs use reST.
Plain Old Documentation (POD) is used for documenting Perl and Perl modules/programs.
It lacks support for tables and therefore is not eligible.
Similarly to Markdown, AsciiDoc is not tied to a specific programming language community. It is more feature-rich than Markdown, however, and has a single specification which is currently being standardized by the Eclipse Foundation.
There are roughly these 3 options:
Final solution:
Current solution
The user manual is currently maintained as a monolithic text file (
docs/MANUAL
). The formatting uses a set of simple text structuring rules. It is parsed and converted to HTML at runtime byDocumentGenerator
.SectionedDocumentViewController
presents the user with a list of the manual sections. When the user selects a section the HTML content is presented to the user byDocumentViewController
using an instance ofWKWebView
.Pros of the current solution:
Cons of the current solution:
Rationale for a change
The main rationale why the current solution needs to be changed is the pure-text approach of the manual. Without illustrations it can be very difficult to explain some aspects of the user interface - a prime example is the function of all the buttons.
A secondary rationale is that, in order to understand the app, the user may want to consult the manual in parallel to using the app. To a certain extent this is possible with the current solution, because the manual is presented in a separate tab of the UI, so to read the manual the user does not have to close the part of the app that they are currently interacting with - they only need to switch tabs. Nevertheless, they can never see the UI they want to know something about and the manual at the same time.
New solution
The new user manual solution shall have the following high-level properties:
Rationale for the in-app availability of the user manual: It might be tempting to just point the user to the public website to read the manual. However, the user manual must be seen as an integral part of the app, and the user should never find themselves in a situation where they cannot look up how something works just because an external resource is not available. Scenarios: