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

Thomas Petazzoni thomas.petazzoni at free-electrons.com
Thu Aug 4 21:23:18 UTC 2011


Hello,

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.

I have done an initial conversion of the Buildroot documentation to
AsciiDoc and the result can be seen at :

 * http://free-electrons.com/~thomas/buildroot/manual/manual.pdf for
   the PDF version

 * http://free-electrons.com/~thomas/buildroot/manual/manual.text for
   the text version

 * http://free-electrons.com/~thomas/buildroot/manual/manual.html for
   the single page HTML version

 * http://free-electrons.com/~thomas/buildroot/manual/html/ for
   the multiple pages HTML version

Some more improvements can quite certainly be made to the converted
document. However, I'd prefer not to maintain it for a too long time
together with the current documentation, so if the solution of
AsciiDoc gets the attention of the Buildroot community, it'd be nice
to have this merged relatively soon, or at least to not do too many
changes to the current documentation.

Best regards,

Thomas

[1] http://www.methods.co.nz/asciidoc/

The following changes since commit 55cea3b5ef3bd5464420fd610c73e150443d0e67:

  util-linux: add option for libmount (2011-07-29 13:38:49 +0200)

are available in the git repository at:
  http://free-electrons.com/~thomas/buildroot.git asciidoc-manual

Thomas Petazzoni (5):
      manual: convert existing documentation to the asciidoc format
      manual: provide make targets to build the documentation
      remove the old buildroot.html documentation
      remove Glibc_vs_uClibc document
      manual: ignore generated files

 Makefile                                     |   40 +-
 docs/Glibc_vs_uClibc.html                    |  240 ----
 docs/buildroot.html                          | 1819 --------------------------
 docs/manual/.gitignore                       |    4 +
 docs/manual/adding-packages-autotargets.txt  |  167 +++
 docs/manual/adding-packages-cmaketargets.txt |  140 ++
 docs/manual/adding-packages-conclusion.txt   |   10 +
 docs/manual/adding-packages-directory.txt    |   76 ++
 docs/manual/adding-packages-gentargets.txt   |  303 +++++
 docs/manual/adding-packages-gettext.txt      |   44 +
 docs/manual/adding-packages-handwritten.txt  |  165 +++
 docs/manual/adding-packages.txt              |   21 +
 docs/manual/board-support.txt                |   35 +
 docs/manual/ccache-support.txt               |   21 +
 docs/manual/customize-busybox-config.txt     |   24 +
 docs/manual/customize-kernel-config.txt      |   12 +
 docs/manual/customize-rootfs.txt             |   36 +
 docs/manual/customize-uclibc-config.txt      |   32 +
 docs/manual/customize.txt                    |   10 +
 docs/manual/download-location.txt            |   26 +
 docs/manual/external-toolchain.txt           |   84 ++
 docs/manual/getting.txt                      |   23 +
 docs/manual/how-buildroot-works.txt          |   59 +
 docs/manual/introduction.txt                 |   69 +
 docs/manual/manual.txt                       |   32 +
 docs/manual/rebuilding-packages.txt          |   62 +
 docs/manual/using-buildroot-toolchain.txt    |   20 +
 docs/manual/using.txt                        |  183 +++
 28 files changed, 1697 insertions(+), 2060 deletions(-)
 delete mode 100644 docs/Glibc_vs_uClibc.html
 delete mode 100644 docs/buildroot.html
 create mode 100644 docs/manual/.gitignore
 create mode 100644 docs/manual/adding-packages-autotargets.txt
 create mode 100644 docs/manual/adding-packages-cmaketargets.txt
 create mode 100644 docs/manual/adding-packages-conclusion.txt
 create mode 100644 docs/manual/adding-packages-directory.txt
 create mode 100644 docs/manual/adding-packages-gentargets.txt
 create mode 100644 docs/manual/adding-packages-gettext.txt
 create mode 100644 docs/manual/adding-packages-handwritten.txt
 create mode 100644 docs/manual/adding-packages.txt
 create mode 100644 docs/manual/board-support.txt
 create mode 100644 docs/manual/ccache-support.txt
 create mode 100644 docs/manual/customize-busybox-config.txt
 create mode 100644 docs/manual/customize-kernel-config.txt
 create mode 100644 docs/manual/customize-rootfs.txt
 create mode 100644 docs/manual/customize-uclibc-config.txt
 create mode 100644 docs/manual/customize.txt
 create mode 100644 docs/manual/download-location.txt
 create mode 100644 docs/manual/external-toolchain.txt
 create mode 100644 docs/manual/getting.txt
 create mode 100644 docs/manual/how-buildroot-works.txt
 create mode 100644 docs/manual/introduction.txt
 create mode 100644 docs/manual/manual.txt
 create mode 100644 docs/manual/rebuilding-packages.txt
 create mode 100644 docs/manual/using-buildroot-toolchain.txt
 create mode 100644 docs/manual/using.txt

Thanks,
-- 
Thomas Petazzoni


More information about the buildroot mailing list