[gentoo-user] Re: SOT (Slightlt OffTopic): Scriptable Documentation system (HTML/PDF) ?

[Grant Edwards]

On 2017-02-07, Meino.Cramer@×××.de <Meino.Cramer@×××.de> wrote:

> to create documentation about changes in the contents of releases,
> of the installation instruction and in system requirements I need a
> system, which is scriptable and therefore automatable.
>
> Current state is to make or changes manually in the different docs.
>
> Is TeX the right choice for the document generating backend?

Unless you need mathematics-heavy, camera-ready, perfectly typeset
layout to be sent to a book publisher, I'd go with something more
lightweight.

My current favorite is asciidoc (which generates HTML and docbook
directly, and various other formats indirectly).

  https://en.wikipedia.org/wiki/AsciiDoc
  http://asciidoc.org/

For smallish documents I use weasyprint to generate PDF from the html.

  http://weasyprint.org/

For longer documents, I use a2x to generate PDF via docbook using the
fop backend.

  http://www.methods.co.nz/asciidoc/a2x.1.html

The 'asciidoctor' alternative implimentation might be worth looking at
for new projects, since it's in more active development:

 http://asciidoctor.org/

If you don't like the asciidoc markup language, you might want to look
at RST:

 https://en.wikipedia.org/wiki/ReStructuredText
 http://docutils.sourceforge.net/rst.html

Or markdown:

 https://en.wikipedia.org/wiki/Markdown
 http://daringfireball.net/projects/markdown/

If you _are_ generating a textbook or academic paper with a lot of
equations, there's still nothing that beats (or even comes close to)
TeX/LaTeX.

-- 
Grant Edwards               grant.b.edwards        Yow! I feel better about
                                  at               world problems now!
                              gmail.com