Suggestion regarding the documentation
- Nebur
- Offline
- Junior Member
- Posts: 35
- Thank you received: 13
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.
- robertspark
- Offline
- Platinum Member
- Posts: 915
- Thank you received: 216
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.
- BigJohnT
- Offline
- Administrator
- Posts: 7330
- Thank you received: 1176
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.
- Nebur
- Offline
- Junior Member
- Posts: 35
- Thank you received: 13
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.
- BigJohnT
- Offline
- Administrator
- Posts: 7330
- Thank you received: 1176
JT
Please Log in or Create an account to join the conversation.
- snowgoer540
- Offline
- Moderator
- Posts: 2391
- Thank you received: 782
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.
Please Log in or Create an account to join the conversation.
- Nebur
- Offline
- Junior Member
- Posts: 35
- Thank you received: 13
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.
- yeltrow
- Offline
- Senior Member
- Posts: 71
- Thank you received: 3
Please Log in or Create an account to join the conversation.
- robertspark
- Offline
- Platinum Member
- Posts: 915
- Thank you received: 216
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.
- snowgoer540
- Offline
- Moderator
- Posts: 2391
- Thank you received: 782
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.