bug#13520: Some documentation improvements for 'dist' targets & opts (was Re: bug#13520: incomplete type of distribution in "List of Automake options" chapter)

[Stefano Lattarini]

On 01/21/2013 11:11 PM, Roumen Petrov wrote:
> Hi automake developers,
> 
> Current (2013-01-21) automake 1.13 manual
> http://www.gnu.org/software/automake/manual/automake.html
> list quite short distribution types in chapter 17.2 List of
> Automake options.
>
Actually, only 'dist-xz' wasn't mentioned.  Which I fixed with the
attached patch.

> It seems to me up to date list is in chapter "14.5 The Types
> of Distributions"
>
Indeed (but note there is no corresponding option to 'dist-gzip',
since that is enabled by default).

> List of supported types in "14.5 The Types of Distributions"
> is alphabetical.  Probably default could be listed first
> followed by other (+0 to change order).
>
Good idea (and could also explicitly identified as the default
one); see the second attached patch.

While at it, I've thrown in some other miscellaneous improvements
to the descriptions of the 'dist-*'.  See third patch.

I've also make clear the 'shar' and 'tarZ' are obsolescent,
and better avoided (see discussion about automake bug#13324
for more background).  See the fourth patch.

> 
> Final paragraph in chapter 14.5 is "The rule dist (and its
> historical synonym dist-all) will create archives in all the
> enabled formats, Options[HREF!]. By default, only the dist-gzip
> target is hooked to dist. " What about to change HREF "#Options"
> (chapter 17 "Changing Automake's Behavior") to exact reference>
> "#List-of-Automake-options"(chapter 17.2 "List of Automake options") ?
>
Good idea as well.  Done with the fifth patch.

Every point should have been addressed, so I'm closing this report.

Thanks,
  Stefano

0001-docs-document-dist-xz-together-with-the-other-dist-o.patch
Description: Text Data

0002-docs-make-even-clearer-dist-gzip-is-the-default.patch
Description: Text Data

0003-docs-improve-documentation-of-dist-targets-slightly.patch
Description: Text Data

0004-docs-dist-shar-and-dist-tarZ-are-obsolescent-today.patch
Description: Text Data

0005-docs-more-precise-cross-reference.patch
Description: Text Data