Re: style of reference API documentation

2025-01-04 Thread Jim Meyering
On Sat, Jan 4, 2025 at 12:22 AM Bruno Haible wrote: > Hi Jim, Hi again :-) > > I'm surprised that you would use "more sources use Y" as a rationale > > for using Y. > > I do so for language-related topics. Because language gets defined by > how people use it in their majority. > > Like you, I'm

Re: style of reference API documentation

2025-01-04 Thread Bruno Haible via Gnulib discussion list
Hi Jim, > I'm surprised that you would use "more sources use Y" as a rationale > for using Y. I do so for language-related topics. Because language gets defined by how people use it in their majority. Like you, I'm not generally in favour of accepting majority votes - for determining what are

Re: style of reference API documentation

2025-01-03 Thread Jim Meyering
On Fri, Jan 3, 2025 at 8:04 PM Bruno Haible via Gnulib discussion list wrote: > > Paul Eggert wrote: > > I'm more familiar with the longstanding tradition of Emacs, where the > > manual says "This function returns X." and the doc strings (which is > > closer to what we're talking about here) say "

Re: style of reference API documentation

2025-01-03 Thread Bruno Haible via Gnulib discussion list
Paul Eggert wrote: > I'm more familiar with the longstanding tradition of Emacs, where the > manual says "This function returns X." and the doc strings (which is > closer to what we're talking about here) say "Return X." In both cases > English-language sentences are used. > > Of course other s

Re: style of reference API documentation

2025-01-03 Thread Paul Eggert
On 2025-01-03 13:09, Bruno Haible wrote: Paul Eggert wrote: * The comments in string.in.h should be imperative sentences. E.g., say "Return true if ..." not "Returns true if ...". Doing it this way is a bit briefer and is more likely to result in valid English sentences. You know that I disagre

Re: style of reference API documentation

2025-01-03 Thread Bruno Haible via Gnulib discussion list
Paul Eggert wrote: > * The comments in string.in.h should be imperative sentences. E.g., say > "Return true if ..." not "Returns true if ...". Doing it this way is a > bit briefer and is more likely to result in valid English sentences. You know that I disagree with that. The style that I am us