[squid-dev] RFC: Squid documentation upgrade

[Amos Jeffries]

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".


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


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