Hi Davor,
Ah now at least I have something I can disagree with :-)
First, in the future, please cut such changes into multiple patches. It's
fine to have a large patch to fix typos and formatting, but it's a real
pain to also have content changes to review in the same patch, as comments
may come from different people each with their respective knowledge, and
you may have to redo the whole patch just to adapt certain parts. Also
it can make it very very hard to backport. It's better to have a big
change for typos, then one change per topic so that some of them may be
backported to old versions (eg: 1.6) and others more recent ones.
Second I don't agree with some of the formating changes. On a few occasions,
probably in order to limit the amount of reformating, the changes led to
incomplete lines, resulting in text looking like this:
This is a first sentence which ends with a dot.
This is a second sentence.
This is a third sentence ending here.
These look really ugly and are hard to read. The reason is that normally
in order to go to next line, you need either to have too large a word that
it cannot fit in the remaining place on the same line, or to start a new
paragraph, in which case a line has to be skipped. So there are two options
for the above:
1) you really wanted paragraphs so blank lines are needed (though most
often it will not be the case because half-line paragraphs are often
ugly and/or wrong) :
This is a first sentence which ends with a dot.
This is a second sentence.
This is a third sentence ending here.
2) in fact you just wanted to adapt the sentences within a same paragraph
and that gives something like this:
This is a first sentence which ends with a dot. This is a second
sentence. This is a third sentence ending here.
Even if it requires re-justifying the rest of the paragraph it's no
big deal, what matters is that it remains much more readable.
By the way, consecutive to your fixes, I discovered that there are a
few different rules between french and english regarding spacing around
colons. In english, a very small (1/5 or 1/6 em) space is expected before
a colon, resulting in practice in none being tolerated at all. I also
prefer this form, and had to train myself to place spaces before the
colon for many years after being criticized for not doing it in french.
Now I have to re-learn how not to do it in english. Similarly in english
they don't put a space before the question or exclamation mark while we
put it in french (given that it's as high as a character I tend to always
place one). Thus you can certainly count on me to continue to make such
mistakes in the doc... I found a good lecture on the subject here :
https://english.stackexchange.com/questions/67394/spaces-around-a-colon
Then I have some comments below:
On Fri, Dec 29, 2017 at 02:48:09AM +0100, Davor Ocelic wrote:
> Content:
>
> Add/clarify the following points:
>
> - Interpretation of variables does not work outside of double quotes;
> dollar signs are treated literally.
In fact that's already what was mentionned. The term "weak quoting" was
used there as well as in a number of other places, and defined early in
the section as being enabled using double quotes. Actually I like the
principle of distinguishing weak vs strong quoting, as it makes it easier
to remember which one lets variables be evaluated and which one does not.
Also once we later improve the config parser to support several encapsulated
quoting layers, it will be easier to speak about weak quoting than double
quoting when this one will become unclear. It's just like when people do
this in shell :
a="$(cat "b c")"
You quickly figure that the double-quoting term is not appropriate anymore,
as we don't have '"$(cat "' and 'b c")"' but the quotes are nested.
> - Global directives ca-base and crt-dir are only available with
> USE_OPENSSL=1.
Good catch!
> - The chroot directory can be empty and by default it does not require
> any files to be present in it.
It should always be empty. I don't see a single case where files are
needed there.
> - Files to lua-load must be present in chroot.
This is not true, and I'd even say that this would partially defeat the
purpose of a chroot if we start to install lots of stuff into it. And
that's fortunate, since some of us use an empty dir such as /var/empty
for the chroot!
> - Remove nbproc warning of:
> USING MULTIPLE PROCESSES IS HARDER TO DEBUG AND IS REALLY
> DISCOURAGED
I disagree with removing the warning on nbproc, it remains true and we
really don't want to encourage people into using it more than what they
currently do. The vast majority of nbproc users don't need it and only
copied it from other configs thinking that "surely it will be even faster
this way".
> - Add 'stats socket' config examples.
I failed to spot them within all the changes :-(
> - "unix-bind" settings do not affect UNIX sockets created by "stats
> socket".
Indeed!
Care to break your patch into topic changes and resend it ?
Thanks!
Willy
