On 9/30/25 12:12 PM, Pádraig Brady wrote:
We'll incorporate any improvements.
Much appreciated.
yes, having people concentrating on the documentation is great.
From a process perspective - sorry, business language -, what does this mean
exactly?
E.g. if we add a new option to the tool, i.e., to the sources, then the same
commit would add:
[X] tests,
[X] the NEWS entry,
[X] amend the usage() string for --help,
but leave man+texi left aside, and hope that the new option is not missed
by the docs sub-team?
Or do we adjust the texi manual as well, and only leave man behind?
Or?
I'm still not really convinced that having 3 formats for documentation (terse
--help
output, comprehensive man pages and the texinfo manual) is effectively using
our resources,
even with a docs sub-team.
There'll be redundancy of documentation in man vs. texi which yields a large
chance to
diverge, i.e., to omit details in the one or the other format, or - even worse
- that
the content of one format contradict to the other.
How do we ensure + verify that this doesn't happen?
As long as there's no "single truth" of documentation, and all the other formats
(man, pdf, html, info, ...) get generated out of that, I don't see how we could
do that.
And at least the given man structure (synopsis, ..., see also) seems to be more
limited than what the mor enatural navigation in Texinfo-based documentation
(info,
pdf, html, ...) allows.
Finally, as someone mentioned: the translation results are linked somewhere
into the upstream
release and the downstream build process. How would that change?
That said, I don't currently want to think where the man pages are stored
(separate git repo
or included), and it's more important how such a documentation change modifies
the
development process, how it decreases effort while still improving the
consistency of the
documentation for the user.
Have a nice day,
Berny
