[Buildroot] [RFC] Using AsciiDoc for the Buildroot manual
Peter Korsgaard
jacmet at uclibc.org
Fri Aug 5 07:44:12 UTC 2011
>>>>> "Thomas" == Thomas Petazzoni <thomas.petazzoni at free-electrons.com> writes:
Hi,
>> One comment though: how will you ship buildroot? Will the generated
>> manuals be included in the official tarballs?
>> I think it should. Otherwise, a new user will have nothing but the
>> individual txt files, which are not convenient to read directly
>> because of the number of files. In order to get 'real' documentation,
>> he'd already have to know that there are make targets for it, he'd
>> need at least asciidoc to get a full manual.txt and possibly docbook
>> to get pdf or html output.
Thomas> This is a question, of course. Peter has raised the same
Thomas> comment on IRC when I quickly presented the proposal, some days
Thomas> ago.
Thomas> I agree that somehow a generated version of the documentation
Thomas> should be part of the release tarballs. The generated
Thomas> documentation should also be on the website, for every
Thomas> Buildroot release.
Thomas> For the first part, I guess the "make release" target can be
Thomas> extended to generate the documentation and then include it into
Thomas> the tarball, but I think this is something to be discussed with
Thomas> Peter.
Indeed. For releases I think atleast the text and single-html version
should get included in the tarball. We also need to setup something with
a git hook to regenerate (some of) the documentation on the server
whenever any of the source files changes. Currently the website is
simply a git checkout managed from cron on the server, and there's no
asciidoc on the server, but presumably that's just a question about
asking the osuosl.org guys for it.
Thomas> What would be great is at least to reach to a decision on
Thomas> whether or not converting the documentation to AsciiDoc is
Thomas> desirable or not. If it is, then I can start collecting patches
Thomas> to fix issues related to the conversion or improvements to the
Thomas> documentation in AsciiDoc format, waiting for the next release
Thomas> cycle to start to get this new documentation format merged.
Well, so far I've only heard positive feedback, so I would say: Go for
it!
--
Bye, Peter Korsgaard
More information about the buildroot
mailing list