[SD45T-2]

Hi,

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?

[YoRyan]

Welcome aboard! I'm still new here, but having just updated the manual, I'm in a position to offer some relevant advice.

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.

[R H Steele]

YoRyan, on 08 May 2020 - 05:35 PM, said:

Welcome aboard! I'm still new here, but having just updated the manual, I'm in a position to offer some relevant advice.

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.

First, I am assuming there probably was or still is a very good reason to use the method you outlined...that I have no clue about.
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

[SD45T-2]

Okay, it seems I have to go into coding land here. (Knows C++, and has worked with HTML and CSS in the past.)

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.

[YoRyan]

R H Steele, on 08 May 2020 - 07:21 PM, said:

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

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:

Okay, it seems I have to go into coding land here. (Knows C++, and has worked with HTML and CSS in the past.)

If you know HTML, that's great! Sphinx conveys the same information, just with a different and heavily condensed syntax.

[eugenR]

SD45T-2, on 08 May 2020 - 11:06 AM, said:

Hi,

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

[R H Steele]

YoRyan, on 08 May 2020 - 11:45 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.

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

[mrmosky]

As an observer, it seems to me that there are two skill sets required here. One is the skill to do technical writing, and the other is skill with several software tools.

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

[cjakeman]

mrmosky, on 09 May 2020 - 09:15 AM, said:

As an observer, it seems to me that there are two skill sets required here. One is the skill to do technical writing, and the other is skill with several software tools.

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?

[SD45T-2]

Would sometime next week be good? I'm the one who started the thread, may as well continue with it.

[James Ross]

mrmosky, on 09 May 2020 - 09:15 AM, said:

As an observer, it seems to me that there are two skill sets required here. One is the skill to do technical writing, and the other is skill with several software tools.

I think it depends.

If you're writing a complex section of the manual, with tables, figures, and such, you will need to be able to build the manual to validate that you've got it right. There are plug-ins for editors that can help with this.

But if you're fixing a mistake, or adding a simple paragraph here or there, you would be fine to use the "Edit" button on the GitHub site. It'll walk you through to a PR.

mrmosky, on 09 May 2020 - 09:15 AM, said:

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.

You could certainly collaborate like that, but I'd recommend at least trying GitHub's built-in editing as an option.

R H Steele, on 08 May 2020 - 07:21 PM, said:

First, I am assuming there probably was or still is a very good reason to use the method you outlined...that I have no clue about.

As with everything, there are pluses and minuses for both the original Word file we used, and the new reStructuredText/Sphinx we use now.

The Word file was easy for someone to simply open up and start making changes, with a nice WYSIWYG interface, but it was troublesome to merge those changes back in if others had also made changes, and the formatting was very messy at times. We could generate a PDF from it.

The reStructuredText/Sphinx files are much easier to merge multiple people's changes to together and solve the messy formatting issue, but you need to install a couple of tools to build/preview changes. We can generate a PDF from it, but we can also generate a beautiful website.

[cjakeman]

SD45T-2, on 09 May 2020 - 05:30 PM, said:

Would sometime next week be good? I'm the one who started the thread, may as well continue with it.

Yes, please, and thanks.

Just send me a private message (PM) when you're ready.

[xavivilla]

I hope they continue with reStructuredText/Sphinx files in the preparation of the manual, it is more convenient than Microsoft Word to locate the modifications and new texts in the manual and to translate it into my native language.

[R H Steele]

James Ross, on 10 May 2020 - 02:40 AM, said:

The reStructuredText/Sphinx files are much easier to merge multiple people's changes to together and solve the messy formatting issue, but you need to install a couple of tools to build/preview changes. We can generate a PDF from it, but we can also generate a beautiful website.

Noted, was unaware of this link, thank you. Still thinking about how to help out. Maybe clean up the office after all the developers leave for the day. http://www.elvastower.com/forums/public/style_emoticons/default/sign_rockon.gif http://www.elvastower.com/forums/public/style_emoticons/default/biggrin.gif

[markus_GE]

cjakeman, on 09 May 2020 - 09:39 AM, said:

[...]
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.

[...]

Trying not to sound like a know-it-all, but couldn't the step-by-step guide you provided when I asked about an introduction to Git for translation purposes be re-used for steps 1, 4 and 5? Or would working on the manual require the use of branches?

Cheers, Markus

PS: I've not forgotten about our collaboration on a translation guide, it's just that I'll take my last exam from my BSc's studies on MAY-18. Thus, electrical engineering tends to occupy most of my days currently.