[squid-dev] RFC: Squid documentation upgrade

[Amos Jeffries]

On 12/10/23 03:32, Alex Rousskov wrote:
> 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,

That re-phrase does not make sense because it is **not** what I wrote.

Specifically your addition "(to Markdown)" is wrong.

Markdown is the proposed source format (in the repository).

The files I listed are **currently** auto-generated from a variety of 
different source formats. My proposal is to change the sources to 
generate **from** Markdown to the various output as-needed.


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

That is a different topic of discussion. I am specifically *not* 
changing the produced outputs content.

> 
> * squid.conf.documented: The format of that file is Squid configuration 
> format, not Markdown.

Well, yes that is the point. I am hoping the text inside COMMENT, and 
DOC sections can use Markdown so we can auto-generate documentation 
files like a squid.conf.8 or the .html more easily with links - without 
making the plain-text form obtuse.

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

IIRC we last discussed it back around 2009-ish with Henrick's proposal 
to split it into a set of multiple files. Are you referring to that?


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

Assumption is wrong. What I mean is that the source document gets 
converted to Markdown and we have the tools auto-generate the man.8, 
info, or pdf files from that as needed by the user/distro.


> 
> * 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).
> 

COPYING is not on the table since that is the mandatory GPL text not 
under our control.

Amos


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