Re: Re* --creation-factor=100 does not show code

[Junio C Hamano <gitster@pobox.com>]

Junio C Hamano <gitster@pobox.com> writes:

> When we say an option's value is expressed in <percent>, unless we
> are careful, people will assume that the valid value the option will
> take will lie between 0 and 100, and you cannot blame them.  IOW,
> while the word "percent" may be 100% correct in your mind, the way
> it is used to describe the feature in "git range-diff --help", it
> was not sufficient to help readers.

Stepping back a bit, I find that saying
"--creation-factor=<percent>" is like giving "--max-size=<bytes>".
They both make it clear that the readers express the number in what
scale, but fails to explain what the number means.  It is especially
hard for readers when the name of the option does not help explain
what the number is, e.g. "max size, size of what?" is a valid
question when dealing with "--max-size", and without the question
answered, the readers cannot decide what value they want to give to
achieve the effect they want.

the reader would want to know what it is (e.g. maximum memory that
is allowed to be allocated on heap) and how it is measured (i.e. in
bytes).  The former helps the readers guess what a reasonable value
they want to specify is (e.g. "I can afford to dedicate yMB"), and
the latter is essential for the readers to decide how exactly they
express what they chose (e.g. "I want to give yMB, but it is
measured in bytes, so I'll write y * 10^20 here").  We need both.

So _after_ they decide that 1.20 is the right number they want to
give to --creation-factor, the knowledge that the number is
expressed as percent does help them to write --creation-factor=120
correctly (not --creation-factor=1.20).

But for readers to come up with the number 1.20, there needs a
better explanation of what the number means in the first place.  "Go
read the algorithm section" is better than having nothing there, but
we should be able to do better by having a simple-to-understand
single paragraph description.

Thanks.