[Buildroot] [RFC] Using AsciiDoc for the Buildroot manual

Grant Edwards grant.b.edwards at gmail.com
Thu Aug 4 22:56:24 UTC 2011

On 2011-08-04, Thomas Petazzoni <thomas.petazzoni at free-electrons.com> wrote:

> The Buildroot documentation was started by myself in December 2004
> (see commit 32fcf718f82c241e890af8c7ccc10ef6c438331a), and at that
> time the amount of documentation was relatively light, so the single
> HTML file was seen as an appropriate solution to write the
> documentation.
> Since then, the documentation has expanded quite a bit, and I intend
> to do some more important additions to the documentation in the near
> future, but I feel like the hand-written HTML format is a bit
> annoying.
> Therefore, this set of patches proposes to switch the documentation
> over to the AsciiDoc format [1]. It is a very simple text-baseda
> format, from which you can generate HTML (single page or splitted),
> PDF, text, and more.

Sounds like a great idea to me.

I use asciidoc for the internal user's manual for the platform which
runs the results of my buildroot use.  That document weighs in at
about 90 pages (in USLetter PDF format).  I find asciidoc very easy to
work with, and it's a lot less work than hand-coded HTML or using
something like OpenOffice/LibreOffice.

FWIW, I prefer the PDF produced by the fop backend over that produced
by dblatex, but that's a matter of taste (I usually use the HTML
version of my document).

I also agree 100% with the decision to keep the option of a
single-HTML-page document. Splitting up documents in to dozens or even
hundreds of separate HTML pages makes them almost impossible to

Grant Edwards               grant.b.edwards        Yow! Pardon me, but do you
                                  at               know what it means to be
                              gmail.com            TRULY ONE with your BOOTH!

More information about the buildroot mailing list