Re: Plain text matching with regex: RE_PLAIN

[Reuben Thomas]

On 19 September 2010 14:33, Bruno Haible <address@hidden> wrote:

Thanks for the explanation of --local-dir.

>> 2. There's a remark that is unclear to me: "(This kind of kitchen-sink
>> module is not needed when you
>> use the @command{gnulib-tool} option @samp{--makefile-name}.)" How
>> does --makefile-name help in this case?
>
> It doesn't force you to move stuff that you would have written in a
> Makefile.am in a gnulib module description; it allows you to keep the
> Makefile.am like you originally wanted.

OK, I didn't understand that at all from the manual. Perhaps you could clarify?

> People try to read a minimum of documentation usually.

Sure. I ended up reading the page (it's about a page in DVI) several
times because it didn't hang together for me. It would be nice not to
have to do that.

> They don't want
> to read details just to understand a little later what they can use them
> for. For this reason, I write documentation on purpose in a way that
> presents first the possible uses and then only the gory details. (At
> least for those pieces of software where the uses are limited.)
> First I answer the question "What can I do with this software?",
> then only the question "How do I do it?"

I agree with this reasoning. If the software doesn't do what you want,
then you can stop reading before worrying about the how.

I think a very simple change would in fact have helped my
understanding: "This means:" to "For example:" or "Among other things,
you can:" (this latter also has the advantage of obviating the need to
start each bullet point with "You can").

I also find the last paragraph a little unclear. Suggested modification:

"Please make wise use of this option.  It also allows you to easily
hold back modifications you make to Gnulib macros in cases it may be
better to share them."

to:

"Please use this option wisely. It allows you easily to keep
modifications to Gnulib private, when it's often better to share
them."

-- 
http://rrt.sc3d.org