[squid-dev] RFC: Squid documentation upgrade

[Alex Rousskov]

On 2023-10-11 02:25, Amos Jeffries wrote:
> Hi all,
> 
> As those familiar with Squid sources will know the documentation of 
> Squid is currently spread across various formats. Some custom ones, and 
> some very outdated.
> 
> So far we have a casual agreement amongst the core dev team to use 
> Markdown when reasonably possible. If anyone has issues with that please 
> chime in ASAP, otherwise I shall continue under the assumption that we 
> are good to make it "official".

FWIW, I (still) agree that we should use Markdown as human-friendly text 
input format, where reasonable.


> I am looking at the <https://pandoc.org/> Markdown tools as possible 
> replacement of linuxdoc tools to translate automatically the following 
> documentation outputs:
>   * release notes,
>   * squid.conf.documented,
>   * the .man / .info / .pdf files,
>   * the INSTALL and QUICKSETUP files

I do not know what "translate [squid.conf.documented and .pdf] 
automatically" (to Markdown) means to you in this context, especially 
since (in the official squid repository) "linuxdoc tools" are only used 
in release notes context. Reaching a rough agreement on what to change, 
how to change it, and where to change it before changing it may be 
prudent. Here are a few comments to bootstrap that process:

* release notes: I recommend discussing changes to release notes 
maintenance and structure before changing their format. It would be nice 
to address several persistent problems that we often bump into when 
working on release notes PRs.

* squid.conf.documented: The format of that file is Squid configuration 
format, not Markdown. FWIW, I am against changing the entire cf.data.pre 
format to Markdown. I am against keeping cf.data.pre as is but 
translating squid.conf.documented format (or portions thereof) to 
Markdown (especially if that requires changes in squid repository). We 
have discussed how cf.data.pre and friends should be restructured and 
reformatted. We should finish those discussions and implement those 
changes instead.

* .man, .info, .pdf files: Your call (assuming .8 and similar source 
files in squid repository remain unchanged).

* INSTALL and QUICKSETUP: I support rewriting these and other top-level 
[A-Z]* files in Markdown, where possible. The other candidates are 
CONTRIBUTORS, COPYING, CREDITS, ChangeLog, README, and SPONSORS(.list).


HTH,

Alex.


> This would impact anyone building Squid packages from our repository 
> instead of the formal release bundles. As well as our testing 
> infrastructure.
> 
> The tools are GPL with sources public in github, so SHOULD be easily 
> available everywhere. At the very least it has been available in both 
> Debian and RHEL distributions for many years. If this change to Squid 
> build requirements is an issue for anyone please speak up.
> 
> 
> Cheers
> Amos
> _______________________________________________
> squid-dev mailing list
> squid-dev at lists.squid-cache.org
> https://lists.squid-cache.org/listinfo/squid-dev