Helping with the manual.
#1
Posted 08 May 2020 - 11:06 AM
It seems that one of the biggest holdups in regards to OR development seems to be the manual. With me having a certification in Microsoft Word, and having passed a course on writing technical documents I would like to offer my services to be the caretaker of the Open Rails manual.
Where do I start?
#2
Posted 08 May 2020 - 05:35 PM
Unfortunately, OR doesn't use Microsoft Word; the documentation is written in Sphinx, which is a markup language like HTML, TeX, or Markdown. The Sphinx processor is written in Python, so you'll need an up-to-date installation of that on your machine. The manual text itself is stored as part of the Open Rails source code, so you'll also need the Git source control system to check out a copy of the code, and an account at GitHub so you can submit pull requests (proposed changes) back to the OR team.
Once you have all the required software, you can just pick a sparsely covered topic, start writing, and submit changes. But if you're writing on a developer-oriented topic, it helps tremendously to have a copy of Visual Studio, too, so you can look up classes and functions in the OR source code. And it helps to know C# code, of course.
If you've never used Python/Sphinx/Git before, I would be happy to provide some additional tips.
#3
Posted 08 May 2020 - 07:21 PM
YoRyan, on 08 May 2020 - 05:35 PM, said:
Unfortunately, OR doesn't use Microsoft Word; the documentation is written in Sphinx, which is a markup language like HTML, TeX, or Markdown. The Sphinx processor is written in Python, so you'll need an up-to-date installation of that on your machine. The manual text itself is stored as part of the Open Rails source code, so you'll also need the Git source control system to check out a copy of the code, and an account at GitHub so you can submit pull requests (proposed changes) back to the OR team.
Once you have all the required software, you can just pick a sparsely covered topic, start writing, and submit changes. But if you're writing on a developer-oriented topic, it helps tremendously to have a copy of Visual Studio, too, so you can look up classes and functions in the OR source code. And it helps to know C# code, of course.
If you've never used Python/Sphinx/Git before, I would be happy to provide some additional tips.
Now for the uniformed question --- Why isn't the manual written using Adobe Acrobat, and that finished pdf is then "translated" into all the other rigamarole you mentioned. Perhaps that way the development team might have more help in keeping manual up to date. Regards, Gerry
#4
Posted 08 May 2020 - 07:22 PM
I'm installing all of those things, and I'll see how I can contribute after the semester ends next week.
Edit: In regards to Gerry's comment above, it seems like a way of automatically churning out PDFs in a specific format.
#5
Posted 08 May 2020 - 11:45 PM
R H Steele, on 08 May 2020 - 07:21 PM, said:
PDF's are finalized documents intended to be sent directly to the printer. They do not include enough formatting information to be easily translatable to other formats. (Notice that if you copy and paste large sections of text from a PDF, you often dredge up garbage spaces and blanks that you had no intention of copying.) You can't convert a PDF to an HTML any more easily than you could convert the RunActivity.exe executable to C# source code.
In addition, plaintext markup languages can be easily split up and patched, so multiple people can work on different sections at once, and the Git version control can easily incorporate all of their changes.
SD45T-2, on 08 May 2020 - 07:22 PM, said:
If you know HTML, that's great! Sphinx conveys the same information, just with a different and heavily condensed syntax.
#6
Posted 09 May 2020 - 03:37 AM
SD45T-2, on 08 May 2020 - 11:06 AM, said:
It seems that one of the biggest holdups in regards to OR development seems to be the manual. With me having a certification in Microsoft Word, and having passed a course on writing technical documents I would like to offer my services to be the caretaker of the Open Rails manual.
Where do I start?
Good Idea to work on Openrails Manual
Specially in the section Signalling exist many not documented functions
http://www.elvastowe...ode-signalling/
The Files for the Manual are together with the code in Github (IE doesn't work anymore):
https://github.com/openrails/openrails
with the green Button at the right, you can download all source of Openrails as a zipfile, without sign in.
The Files for the Manual are under:
\Source\Documentation\Manual
The Manual- Files are here:
https://github.com/o...entation/Manual
regards
EugenR
#7
Posted 09 May 2020 - 06:55 AM
YoRyan, on 08 May 2020 - 11:45 PM, said:
In addition, plaintext markup languages can be easily split up and patched, so multiple people can work on different sections at once, and the Git version control can easily incorporate all of their changes.
YoRyan -- Thank you for taking your time to provide some illumination --- appreciated. I was hoping to help out, but now see I'm woefully under-prepared. Clears up some other questions I had about the manual. Thanks for the work on the current update you just completed. Gerry
#8
Posted 09 May 2020 - 09:15 AM
Wouldn't it be possible to split these up between two people? Someone who is a good technical writer could produce a manual section in whatever word processor they are comfortable with, and then a second person could easily cut and paste that text into the correct language for the manual.
At the moment, the requirements are too restrictive to attract helpers maybe.
Geoff
#9
Posted 09 May 2020 - 09:39 AM
mrmosky, on 09 May 2020 - 09:15 AM, said:
The "skill with several software tools" sounds more scary than it is. All that is needed is Microsoft's Visual Studio (free community edition) and an account on GitHub.com.
I think that what we lack is a good set of instructions that show:
- How to pull down the latest version of Open Rails from the GitHub repository,
- How to make an edit
- and re-build the PDF so you can see the result of your work.
- How to push your work back to GitHhub
- and request that it be reviewed and pulled into the Testing version.
I would offer myself but am a bit stretched just now. Happy to collaborate though with a volunteer.
Any takers?
#10
Posted 09 May 2020 - 05:30 PM