Re: [hatari-devel] Question on docs building

[Eero Tamminen <oak@xxxxxxxxxxxxxx>]

Hi,

On 5/17/20 1:31 PM, benoît tuduri wrote:
> First, I'm apologize if this is the wrong place to ask that question.
> I'd like to know how you write documentation like the manual... on the hand?

It's manually edited HTML and regular ASCII.


> If so, wouldn't you like to have a format that is easier to maintain
> like with asciidoc tools, etc? >
> Which one would you use if you had to choose one?

The problem with these "easier" formats is
that there are so many to choose them, they
come and go.  Building the final documentation
may also be a problem for users, if it e.g.
requires going through LaTeX.

I've used quite a few documentation systems since
90's, starting from TeX & SGML.  For longer docs I
still prefer LaTeX (with LyX GUI), but I don't
think that really suits Hatari. :-)


Of the lightweight markup languages I actually
prefer AsciiDoc syntax, and looking at this:
https://en.wikipedia.org/wiki/Lightweight_markup_language

It seems to support:
* _both_ HTML import & export
* at least 3 levels of headers
* text styles including code/monospaced
* tables

What about:
* inline images
* index generation
* table cell alignment
?

	- Eero