[Mesa-dev] docs: consistent language

Wed Mar 24 19:32:40 UTC 2021

+1 to recommending the use of US English spelling in Mesa docs & code.

I certainly would not want to impose any heavy burdens on contributors
who are accustomed to UK/AU spelling.  I don't think we should block any
patches because of UK/US/AU spelling, and people should feel free to
not think about it and use their normal language when contributing.

Consistency can be nice when searching for code.  The main reason I like
fixing typos and pure misspellings (wrong in all dialects) in our code
is to improve searchability.  It's usually no trouble to read a sentence
with some typos.  But try searching for a function or enum where the
name has a typo, and you likely won't find it, and then have to waste
time digging through the code until you finally find it.

US/UK/AU spelling variations usually haven't come up in that regard,
though I did notice that midgard and llvmpipe are using "optimise"
(16 uses) in some functions, while optimize (1087 uses) is more common.
One awkward bit is that Gallium hooks like pipe->finalize_nir() already
impose a US spelling.  Having the driver set pipe->finalize_nir =
driver_finalise_nir seems a bit awkward.  On the other hand, using both
finalize_nir (US spelling to match the hook) and optimise_nir (UK
spelling because there's no hook to match) becomes internally
inconsistent...so maybe it's better to just pick one.

Having a policy of preferring US spelling seems nice, as we could
auto-ack any patches to make the docs and code consistent, like we
already do for typo fixes and pure spelling or grammatical fixes.
That way we remove the need for debate on each encounter, while also
not blocking people's work and contributions over trivial matters.

--Ken

On Tuesday, March 16, 2021 5:19:43 AM PDT Erik Faye-Lund wrote:
> Just one detail to fill in:
> 
> I just got a question on #dri-devel if this suggestion would place an
> additional burden on most developers to additionally look up every word
> of new documentation to see if it's US or UK English.
> 
> I'm not proposing to place any additional burden on people writing
> docs. I think it's fine if people do a best-effort (which arguably can
> be low; this isn't a very important detail), and then we'll either
> catch things during reviews or fix it up afterwards.
> 
> It's not like the Mesa docs are perfect in terms of spelling or grammar
> anyway, I just want to resolve which of the forks in the road we follow
> trying to clean things up ;)
> 
> On Mon, 2021-03-15 at 13:44 +0100, Erik Faye-Lund wrote:
> > TLDR; I'm proposing to standardize on US English in our public-facing
> > documentation.
> > 
> > I proposed an MR a while back that changed the only occurrence of the
> > UK English spelling "optimisation" for the US English spelling
> > "optimization", which is already used 34 times in the docs. I've done
> > similar changes in the past.
> > 
> > But this time Ian brought up the good point that picking a preferred
> > language should probably be done using group consensus on the mailing
> > list than just picking what's currently most popular.
> > 
> > So, I hereby propose to pick US English as our default language for
> > user-facing documentation.
> > 
> > I'm not proposing to force anyone to use a particular English variant
> > for things like comments, commit messages or variable names. I don't
> > think there's much value in enforcing that, and I think it'd be
> > perfectly fine if any particular driver wanted to pick a particular
> > variant of English.
> > 
> > The main reason I want to standardize on an English variant is that
> > I'm
> > trying create a word-list for domain-specific/technical language to
> > detect spelling mistakes in the docs more easily. And not having to
> > add
> > both US and UK English words makes this list easier to maintain. I'm
> > not planning on going 100% systematically though the dictionary to
> > detect UK English words that might be in my system dictionary, just
> > to
> > fix the words that currently cause me (a tiny amount of) pain ;)
> > 
> > The main reason why I'm proposing US English over for instance UK
> > English is that this seems to be the dominant variant currently in
> > the
> > documentation. So it seems like the pragmatic choice to me.
> > 
> > Thoughts? Any objections to sticking to US English in the docs?
> > 
> > The MR in question:
> > https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/8572
> > 
> > Ian's response:
> > https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/8572#note_808593
> > 
> > Previous changes:
> > https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/6864
> > https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/6894
> > 
> > 
> > _______________________________________________
> > mesa-dev mailing list
> > mesa-dev at lists.freedesktop.org
> > https://lists.freedesktop.org/mailman/listinfo/mesa-dev
> 
> 
> _______________________________________________
> mesa-dev mailing list
> mesa-dev at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/mesa-dev
> 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: This is a digitally signed message part.
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20210324/c513e65b/attachment-0001.sig>