On Thu, Jan 09, 2020 at 03:27:17PM +0100, Tim Düsterhus wrote:
> Willy,
> 
> Am 09.01.20 um 04:07 schrieb Willy Tarreau:
> > I'm personally not opposed to this at all, however after reading the link
> > above and given that Lua's concept of "path" is all but obvious as described
> > in the link above, we definitely need a bit more text in the doc to quickly
> > explain that the path is rather a pattern and that the question mark is
> > replaced by the file in "require", and probably put a short example. Having
> > the link for more details is fine but not as a redirect to figure how to
> > use the config keyword.
> 
> I concede that the HAProxy documentation should mention `package.path`
> to be clear what kind of path it refers to. But I disagree that we
> should explain how this works in detail, because this is not about any
> HAProxy specific stuff, but about the "inner workings" of Lua and thus
> it's best explained by the Lua documentation. We would only be able to
> "re-explain" the existing documentation, but probably worse, because we
> miss out on important details.

Except that the terminology here is totally misleading. I didn't understand
your proposed example even when reading the commit message and the proposed
doc. This solely because Lua uses the term "path" to designate a pattern,
while in traditional environments a path is more a list of directories.
*This* must be mentioned. It's not acceptable to have a config documentation
saying "hehe I caught you, you thought you would find the info you were
looking for here, but no, please visit this link instead, and too bad for
you if the net access is down due to haproxy not starting because of the
wrong config you're trying to fix, have a good night sir". I'm not suggesting
to paraphrase the Lua's doc, just to mention the few elements that are
sufficient for someone having to edit an entry to understand what he/she's
doing. The link is then provided to have the details. And by the way it
should also be clear what happens if multiple such directives are specified
(I have no idea).

Regards,
Willy

Reply via email to