From: Peter Korsgaard <jacmet@uclibc.org>
To: buildroot@busybox.net
Subject: [Buildroot] [RFC] Using AsciiDoc for the Buildroot manual
Date: Fri, 05 Aug 2011 09:44:12 +0200 [thread overview]
Message-ID: <87ipqcmhf7.fsf@macbook.be.48ers.dk> (raw)
In-Reply-To: <20110805083926.257f81bc@skate> (Thomas Petazzoni's message of "Fri, 5 Aug 2011 08:39:26 +0200")
>>>>> "Thomas" == Thomas Petazzoni <thomas.petazzoni@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
next prev parent reply other threads:[~2011-08-05 7:44 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2011-08-04 21:23 [Buildroot] [RFC] Using AsciiDoc for the Buildroot manual Thomas Petazzoni
2011-08-04 21:23 ` [Buildroot] [PATCH 1/5] manual: convert existing documentation to the asciidoc format Thomas Petazzoni
2011-08-04 21:23 ` [Buildroot] [PATCH 2/5] manual: provide make targets to build the documentation Thomas Petazzoni
2011-08-04 23:05 ` Yann E. MORIN
2011-08-04 21:23 ` [Buildroot] [PATCH 3/5] remove the old buildroot.html documentation Thomas Petazzoni
2011-08-04 21:23 ` [Buildroot] [PATCH 4/5] remove Glibc_vs_uClibc document Thomas Petazzoni
2011-08-04 21:23 ` [Buildroot] [PATCH 5/5] manual: ignore generated files Thomas Petazzoni
2011-08-04 22:56 ` [Buildroot] [RFC] Using AsciiDoc for the Buildroot manual Grant Edwards
2011-08-05 5:42 ` Thomas De Schampheleire
2011-08-05 6:39 ` Thomas Petazzoni
2011-08-05 7:44 ` Peter Korsgaard [this message]
2011-08-05 8:22 ` Thomas Petazzoni
2011-08-07 19:18 ` Peter Korsgaard
2011-08-07 19:24 ` Yann E. MORIN
2011-08-08 18:20 ` Peter Korsgaard
2011-08-09 15:02 ` Thomas Petazzoni
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87ipqcmhf7.fsf@macbook.be.48ers.dk \
--to=jacmet@uclibc.org \
--cc=buildroot@busybox.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.