[squid-dev] squid.conf future

[Alex Rousskov]

On 2/24/20 3:11 AM, Amos Jeffries wrote:

> While doing some polish to cf_gen tool (PR #558) I am faced with some
> large code edits to get that tool any more compliant with our current
> guidelines. With that comes the question of whether that more detailed
> work is worth doing at all ...

Probably not. Even PR #558 changes might be going a bit too far (or not
far enough). Ideally, we should agree on key code cleanup principles
before doing such cleanup, to minimize tensions in every such PR.
Cleanup for the sake of cleanup should be done under a general
agreement/consent rather than ad-hoc. I am working on the corresponding
suggestions but need another week or so to post a specific proposal.


> For the future I am considering a switch of cf.data.pre to a format like
> SGML or XML which we can better generate the website contents from.

I do support fixing cf.data.pre-related issues -- they are a well-known
constant (albeit moderate) pain for developers and users alike. However,
using writer-unfriendly formats such as XML is not the best solution
IMO. SGML may be a good fit, but that concept covers such a wide variety
of languages that it is difficult to say anything specific about it in
this context (e.g., both raw XML and wiki-like markups can be valid
SGML!). If you meant something specific by "SGML", please clarify.

Automated rendering of squid.conf sources, including web site content
generation, should be straightforward with any good source format,
including writer-friendly formats. Thus, web site generation is not an
important deciding criteria here AFAICT.

IMO, an ideal markup language for cf.data.pre (or its replacements)
would satisfy these draft high-level criteria:

1. Writer-friendly. Proper whitespace, indentation, and other
presentation features of the _rendered_ output are the responsibility of
renderes, not content writers. Decent _sources_ formatting should be
automatically handled by popular modern text editors that developers
already use. No torturing humans with counting tags or brackets.

2. Expressive enough to define all the squid.conf concepts that we want
to keep/support, so that they can be rendered beautifully without hacks.
For example, if we agree that those sections are a good idea, then this
item includes support for introduction sections that define no
configuration options themselves.

3. Supports documentation duplication avoidance so that we do not have
to duplicate a lot of text or refer the reader to directive X for
details of directive Y functionality.

4. Allows for automated validation of internal cross-references (and
possibly other internal concepts that can be validated). Specification
of these cross-references is covered by item 2.

5. Allows for automated spellchecking without dangerous exceptions.

6. Git-friendly: Adding two new unrelated directives does not lead to
conflicting pull requests.

7. Either already well-known or easy to learn by example (as far as
major used concepts are concerned).

8. Can be easily parsed using programming languages that our renderers
are (going to be) written in (e.g., using existing parser libraries). We
should probably discuss whether these renderers should be (re)written in
some specific languages.

9. Translation-friendly. (I do not know what that entails, but I am sure
that others can detail this reqiurement.)

It is unlikely that we can find a language that fully satisfies all the
criteria, but I hope that we can come close. It is not a new/unusual
problem. Let's not rush into rewrites until we agree on this.


> The main point in favour of these is that we already have infrastructure
> in place for ESI and release notes. It would be less work to re-use one
> of those than integrate a new library or tooling for some other format.

Reusing existing infrastructure is a nice bonus, of course, but I think
that any major format rework should be focusing on optimizing for the
long-term. Any infrastructure changes required to render static content
on a web site seem relatively small to me. (And does not ESI support
injection of any content, not just XML-based?)


Thank you,

Alex.