Double spaces in documentation

Why are there so many double spaces all over the GLFW documentation? These occur in most places after a sentence. What is the rationale behind this? It’s honestly quite annoying. It seems like this is really intended, but it’s not intuitive, and if you wish for all documentation to be formatted this way, it should probably be written into the contribution guide.

Two spaces after a full stop used to be a rule, as it helps clarify sentence structure with fixed width fonts. It’s pretty much dropped out of favour these days, though there is evidence to support it being easier to read.

As to why there is a mix I suspect this is due to people erroneously not following prior formatting, and it not being caught in review.

GLFW doesn’t have a style guide in the contribution section, and the normal practice when developing PRs is to stick to the style in use.

I find them very unintuitive and distractive. It stands out as incorrect to me, and I mistook these for typos many times. When I again and again came over them, I started seeing a pattern, and realized that these indeed are intended. Personally, I don’t find any aid in them, even with monospace fonts, but I’ll look for articles about this, as it’ll likely be an interesting read anyway.

While I don’t like the double spaces, I agree with the importance of consistency, and all the documentation should be formatted equally. As the chosen style is double spaces, all those single spaces should be changed.

As this style is not an obvious catch for new contributors, exemplified by my own post, and shown by single spaces approved into GLFW, a style guide with this point in particular, should probably be added to GLFW. I have added it to a private list of issues I’ve run into while getting into GLFW contribution.

It helps my buggy eyes find where sentences begin and end in a paragraph. I don’t find it particularly aesthetic, necessarily, but it has been a significant help and there would be less documentation without it.

Yup, either a typo or an oversight during review.

I’ve tried to write a style guide several times but haven’t been able to both keep it short enough to get read and also include the sharp corners, probably because they’re of my own making. If it’s something you would be interested in writing, brief style guides could be both helpful and a good use of the wiki, so… more on this in the wiki permissions thread, where I will reply as soon as I’m able.

Yeah, sure, I’ve already said yes to such a request in the past, in another thread I created on this forum, but I need time to prepare. I created a few PRs a while ago of mediocre quality, for enhancements to the Cocoa implementation of GLFW, but it isn’t until I got through the video-mode and theming work that I’ve started getting ready for writing contributor guiding. :slight_smile:
I assume you’re referring to the Github meta thread when writing “the wiki permissions thread”, so I guess that means we found a new use for it.

I forgot to state my opinion on this. Can’t edit the reply now, so I’ll have to create a new one. This is reason enough to keep it. If it helps just anyone more than it bothers me, it’s a good reason to keep this style.

1 Like