Hi Stefano, Thanks again for taking the time to review these files.
As before, I've accepted the changes into my copy wherever I haven't
commented otherwise below. Since there is no other natural home for
the texi file, since I wrote it specifically for gnulib, so I'm
attaching the latest version here again so that it doesn't get lost.
On 26 Sep 2011, at 00:28, Stefano Lattarini wrote:
> And this is a quick review about the new documentation ...
>
> On Thursday 22 September 2011, Gary V wrote:
>> needs to be extremely @strong{customisable} and extendable,
>>
> My syntax checker highlight the word `extendable'; maybe we should
> use `extensible' instead?
'extendable' is a legitimate word (as google will testify), but I think
'extensible' is more popular in computing circles, so I've changed it.
>> will fall-back automatically on
>>
> Is "fall back on" grammatically correct? I've always thought that one could
> only say "fall back to" ... (of course I'll defer to the judgement of the
> native speakers on this, that should be crystal-clear).
Either sounds fine to me. Perhaps 'fall-back upon' is more strictly correct.
I've taken your 'fall back to' suggestion in any case.
>> the gnulib defaults; unless you set
>> alternative values here in @file{bootstrap.conf}.
>
>> @cnindex gnulib_path
>> @cnindex gnulib_url
>> @item gnulib_path
>> @itemx gnulib_url
>> Relative path to the local gnulib submodule, and url to the upstream
>> git repository.
>>
> "upstream gir repository" of what exactly? It's not completely clear
> IMHO.
Changed to "upstream git repository for gnulib".
>> upstream repository at @sc{gnu} savannah.
>>
>> @cnindex gnulib_tool_options
>> @item gnulib_tool_options
>> Additional options to pass to @command{gnulib-tool} when it is called.
>>
>> @smallexample
>> gnulib_tool_options='
>> --no-changelog
>> --libtool
>> '
>> @end smallexample
>
>> @cnindex gnulib_precious
>> @item gnulib_precious
>> Normally, @command{bootstrap} removes any macro-files that are not
>> included by @file{aclocal.m4} before it returns, except for files
>> listed in this variable which are always kept.
>>
> Are you sure it is a good idea to do so by default? The potential for
> disruption seems pretty high to me. Note that this is an OBJECTION TO
> THE BEHAVIOUR, not the documentation.
It is nothing irreversible, as only copies of files added by autopoint
are removed. cf doc-comment for `func_clean_unused_macros':
# Autopoint can result in over-zealously adding macros into $macro_dir
# even though they are not actually used, for example tests to help
# build the `intl' directory even though you have specified
# `AM_GNU_GETTEXT([external])' in your configure.ac. This function
# looks removes any macro files that can be found in gnulib, but
# are not `m4_include'd by `aclocal.m4'.
>> @smallexample
>> po_download_command_format=\
>> "rsync --delete --exclude '*.s1' -Lrtvz \
>> 'translationproject.org::tp/latest/%s/' '%s'"
>> @end smallexample
>>
> Could a runtime check be added to bootstap, to ensure that an
> user-overridden `$po_download_command_format' is well formed?
> Or would the ratio burdens/benefits be too high?
Well formed in what respect? Certainly that's a peculiarly finicky bit
of code that you don't want to screw up, so there's definitely scope for
saving hair-pulling if there's a way to catch obviously broken command
specifications here. I don't have any po using projects though, so I
didn't work as hard on making this part fool proof as I did on plenty of
the other features of bootstrap.
Suggestions are always welcome if you have a specific idea on how to
implement an improvement.
>> @cnindex extra_locale_categories
>> @item extra_locale_categories
>> Other locale categories that need message catalogs.
>>
>> @cnindex xgettext_options
>> @item xgettext_options
>> Additional @command{xgettext} options to use. Gnulib might provide you
>>
>> [SNIP]
>>
> I'd like to have it explicitly stated that a project that is not
> interested in NLS support should not worry about these laster three
> variables (`$po_download_command_format', `$extra_locale_categories'
> and `$xgettext_options') at all.
Agreed. I added a short paragraph to each.
>> @node Configuration all kept in @file{bootstrap.conf}
>> @subsection Configuration all kept in @file{bootstrap.conf}
>> All the parameters for running @command{gnulib-tool} and others
>>
> Who/what are these "others"?
Other bootstrap-time commands: libtoolize, autopoint, autoconf as
appropriate to the project being bootstrapped. But I take your point,
and made it more explicit.
>> are maintained in @command{bootstrap.conf}. This is the default
>> usage pattern.
>>
>> In order for this to work, when you wish to add or remove a gnulib
>> module from your package, amend the value of @var{gnulib_modules} in
>> @file{bootstrap.conf} (and similarly for any other parameters) and
>> rerun @command{bootstrap} to import everything anew.
>>
> Doesn't this worsen performance too much? (Sorry if it's a dumb question,
> but my knowledge of gnulib-tool importation/updating process is shaky at
> best).
I thought that too for a long time, and avoided managing gnulib-tool
invocations by this method for that reason. Bruno was patient enough
to explain in a couple of different ways that it actually doesn't save
any bootstrap time at all to treat gnulib-cache.m4 as truth, so I now
use the default method for all my new projects.
Thanks again for the review!
Cheers,
--
Gary V. Vaughan (gary AT gnu DOT org)
bootstrap.tar.bz2
Description: BZip2 compressed data
