Suggestion regarding the documentation

Why does the project use a font with lookalike but wrong characters e.g. for dashes, single-quotes etc.?!
Even stuff that has a text format that suggests to the reader 'this is code' contains this sh*t.

For I don't know how many times copy&pasting stuff from the documentation came back to bite me in the a** because I missed changing one pseudo single-quote.

Thought I should finally take the time to leave a note here hoping for a discussion and a change in the future...
Changing this would seem to be a low-hanging fruit to improve 'accessibility'.





 

being an open source project, you can always fix the documentation as you see fit on GitHub and post your fixes.

the more I dabble with linuxcnc the more I get used to the things that I saw as annoyances and see them more as functional. if it's cutting chips does it matter what the interface or documentation looks like

(axis is now beginning to grow on me... and I am always reading the online docs trying to learn and understand more)

Yes, I know how open source projects work and that I'm free to fix it myself.

Still there are users and developers. This is a hint from a user on an issue. Most likely I - as a user - would spend days to even get a grasp on the documentation build system, while somebody familiar with the system would need 5 minutes to do the actual fix. If I was to contribute time to the project, I'd rather invest it in things that I know how to do.

In my opinion the issue is significant - especially for less computer-literate folks that will get understandably frustrated by the fact that snippets copied from the very documentation fail to work.

Sure - if the doc-system held together by lost knowledge + pixie dust then things might not be that easy...

Hours to decipher my hints? I described the issue right in the first post - dashes and single quotes.
Also that's quite a way of quoting out of context - I didn't say that the issue was significant to _me_ personally. And I also didn't complain or demand to get a fix - it's right in the thread title - a suggestion.

I guess you are 'reading' a tone that isn't there. I'm sorry if you feel bothered by my choice of words or me pointing out an issue without the inclination to gather the required knowledge to fix it myself.

Regarding specific locations, here some examples quickly scrolling through the pdfs:
Every pin name in LinuxCNC_Manual.pdf that contains a dash seems to use the 'wrong' character for the dash (U+2212). This one keeps getting me and others. There's even a tutorial on youtube on linucnc that points out the issue with the wrong chars.
Example from LinuxCNC_Documentation.pdf: py code on page 401 contains the wrong single quotes (U+2019). Another example is on page 450.

I would guess it's a matter of changing some params in the pdf production. No idea.

Anyway - I'm not going to post anything else in this thread. I really don't want to argue or defend myself.

As another user, Thank you. I do appreciate you taking the time to highlight the issue. The last, very specific post you made on the unicode specifics and where you found the exact problem are exactly the sort of troubleshooting help that are needed. I love that LinuxCNC is so good and getting better all the time.

Nebur,

Your last post was very much more useful than your first post as it clearly lists the problem.

It was not apparent that your problem was with the PDF documentation, and it was not clear that the problem was with whatever creates the PDF documentation that it was using the wrong character codes.

I personally have never used the PDF's and just use the online HTML documentation and I don't believe I've had an issue with copy and pasting code into the terminal or into scripts.

Much more useful to understand the problem specifically. I can't be of help in sorting it, but I'm sure its probably more helpful than the first to someone who understands the workings of the PDF'ing tool that linuxcnc uses when it compiles its debs / online docs.