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. _______________________________________________ squid-dev mailing list squid-dev@lists.squid-cache.org http://lists.squid-cache.org/listinfo/squid-dev
