Suggestion regarding the documentation

More
22 Mar 2022 19:26 #238027 by Nebur
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'.





 

Please Log in or Create an account to join the conversation.

More
22 Mar 2022 20:57 #238036 by robertspark
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)

Please Log in or Create an account to join the conversation.

More
22 Mar 2022 21:17 #238039 by BigJohnT
Actually the documents are rather complicated to say the least and not easy to change some things. They get built with some magic I think as I worked on the documents for 10 years and still don't know how they get to their final form.

Open source projects get better when people spend their time to improve the project.

JT

Please Log in or Create an account to join the conversation.

More
22 Mar 2022 22:56 #238048 by Nebur
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...

Please Log in or Create an account to join the conversation.

More
23 Mar 2022 22:36 - 23 Mar 2022 22:37 #238166 by BigJohnT
If you find an easy way to fix it let me know and I'll fix it. Copy and Paste from the pdf docs has annoyed me for a decade or more...

JT
Last edit: 23 Mar 2022 22:37 by BigJohnT.

Please Log in or Create an account to join the conversation.

More
24 Mar 2022 00:48 #238182 by snowgoer540

This is a hint from a user on an issue.

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



If the issue is that significant to you, then perhaps instead of complaining about how not perfect this completely free to you software / software documentation is, and instead of dropping "hints" you could take some time to actually contribute in a constructive way and at least point out the specific examples where you see issues from specific locations so that those of us who are willing to take the "5 minutes to do the actual fix" could do so without hours of trying to decipher your hints. Otherwise it just comes off as ungrateful trolling.

I think you will find that most of the developers here are very willing to help. That said, it's impossible to fix and make everything perfect.
The following user(s) said Thank You: BigJohnT

Please Log in or Create an account to join the conversation.

More
24 Mar 2022 03:03 #238186 by Nebur
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.

Please Log in or Create an account to join the conversation.

More
24 Mar 2022 03:58 #238188 by yeltrow
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.

Please Log in or Create an account to join the conversation.

More
24 Mar 2022 10:34 #238210 by robertspark
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.

Please Log in or Create an account to join the conversation.

More
24 Mar 2022 11:15 #238212 by snowgoer540

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.


Ah, the PDF docs. I do see what you are talking about, but when I check the source that the pdfs are made from, the issue does not exist. I think there are few people on this project who truly understand how the pdfs are generated, and the bad characters are getting added at that point. I am not familiar with that process at all, so it's no easy fix (for me).

Honestly I gave up on the pdf versions a long time ago. The formatting is a bit clunky. Most of the main docs are written in asciidoc, and as such are best viewed in html (which is also local to your PC if you choose to install the docs). The man pages show up correctly in html as well. Alternatively, you could view them at the source, on github. Probably not what you want to hear, but that's the best I can do for now.

For what it's worth, I did spend a bit of time combing through the English docs source and replacing all of the bad unicode characters I could find. I will be pushing that commit at some point here in the next day or so.

Please Log in or Create an account to join the conversation.

Time to create page: 0.264 seconds
Powered by Kunena Forum