[Buildroot] 2011.11: manual improvements

[Thomas Petazzoni <thomas.petazzoni@free-electrons.com>]

Le Wed, 23 Nov 2011 08:23:47 +0100,
Thomas De Schampheleire <patrickdepinguin+buildroot@gmail.com> a ?crit :

> > * The 2011.11-rc1 tarball does not contain a ready-made manual. A
> > user that doesn't know buildroot and searches for the manual, will
> > only find the manual sources in docs/manual. These are readable,
> > but they are not intended for that purpose. I don't think we can
> > expect users to first run 'make manual', and have asciidoc
> > installed. Therefore I think we should provide a ready-made manual
> > in the tarballs. It probably requires a rewrite of the 'release'
> > target, because the current 'git archive' used there will not take
> > along untracked files. One approach is to add the files to the
> > tarball afterwards.

I agree on the need to have a generated version of the manual in the
released tarballs.

> > * I think it should become more clear that the contents of
> > 'docs/manual' are really the manual sources, not the finished
> > manual. One way to do this would be to move them in a subdirectory
> > 'sources' or rename 'manual' to 'manual-sources'.

Hum, not sure this is so important. I know Peter wanted to move the
website sources from docs/* to docs/website/. Many the manual sources
can be in docs/manual/src/ and the generated manual available in
released tarballs stored in docs/manual/.

> > * Suppose a user does execute 'make manual', then it's unclear what
> > the location of the manual is. I think we should print the location
> > when executing the corresponding make targets, and provide a README
> > or similar in docs/manual to explain this. I would actually like it
> > if the manual were generated in docs/manual directly, instead of in
> > 'output'.

That's what I implemented originally, but I was told that it wasn't
correct to generate things within the source tree. If we do support
out-of-tree build, then it's true that we should support the case where
the source tree is kept read-only. I don't feel very strongly about
this.

> I haven't seen any comments regarding this. Still, I think it's
> important to discuss before releasing 2011.11.

I don't think any of those problems are show-stoppers for the release.
They would be nice to have (especially having generated manuals in the
release tarballs), but they can be improved in future releases if not
implemented for 2011.11.

Best regards,

Thomas
-- 
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com