On 8/28/25 2:16 AM, Martin D Kealey wrote:
I should have been clearer: I'm talking about *all* documentation, not just documentation read by users. "Documentation" doesn't only mean info & man pages; it also means natural language text that is intended to be read by developers, including comments in code and whole files such as AUTHORS, CWRU/OS-BUGS/*, README and HISTORY, or read by distributors, in whole files such as CHANGES and INSTALL.
I do not see these as problems.
On Sun, 24 Aug 2025 at 16:59, G. Branden Robinson < [email protected]> wrote:I decline to address how Chet maintains plain text files in his distribution.Well that just side-steps basically everything that triggered me to write about this in the first place. It is exactly "plain text files" that I find particularly vexing.
This seems to be your own particularly maddening itch. Are you arguing that using `word' reduces readability in general? Does anyone besides you think so?
new documentation is still being added that follows this style.For example, since 2011-12-12 (when GNU policy changed to discourage using ` as a quote mark),
This is limited to user messages inside source code.
bash/CHANGES has had 485 lines added that include `quotes like this', at a fairly consistent rate. CHANGES-5.3 alone has 121 instances over 98 lines.
The GNU standards don't say anything about quotes in text files; only messages to users in source files. I'm open to changing user messages, but it's my impression from this text: "By convention, gettext translates the string ‘"`"’ to the opening quote and the string ‘"'"’ to the closing quote" that it's not a big deal. I'll take a look at the man page and texinfo files, but I went over them pretty closely when Branden sent his patches and added .Q. No doubt there are a few remnants.
It's the supposedly "plain text" -- where there's no translation layer -- that's got me worked up.
Evidently.
Some (maybe all) of the HTML files in Bash appear to be manually maintained, as indicated by some very peculiar whitespace.
Such as? All of the documentation html files are generated by either
makeinfo (texinfo source) or man2html (man page source). I'd consider
switching to groff to generate HTML from man pages and dropping man2html;
fewer moving parts.
--
``The lyf so short, the craft so long to lerne.'' - Chaucer
``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU [email protected] http://tiswww.cwru.edu/~chet/
OpenPGP_signature.asc
Description: OpenPGP digital signature
