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