Elvas Tower: Helping with the manual. - Elvas Tower

Jump to content

  • 2 Pages +
  • 1
  • 2
  • You cannot start a new topic
  • You cannot reply to this topic

Helping with the manual.

#1 User is offline   SD45T-2 

  • Engineer
  • Group: Status: Active Member
  • Posts: 667
  • Joined: 28-November 08
  • Gender:Male
  • Location:Louisiana
  • Simulator:OR, Trainz, and Misc. Sims.
  • Country:

Posted 08 May 2020 - 11:06 AM

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?

#2 User is offline   YoRyan 

  • Hostler
  • Group: Status: Active Member
  • Posts: 92
  • Joined: 19-February 20
  • Gender:Male
  • Simulator:Open Rails - testing
  • Country:

Posted 08 May 2020 - 05:35 PM

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.

#3 User is offline   R H Steele 

  • Vice President
  • PipPipPipPipPipPipPipPip
  • Group: ET Admin
  • Posts: 2,488
  • Joined: 14-March 13
  • Gender:Male
  • Location:known universe
  • Simulator:Open Rails
  • Country:

Posted 08 May 2020 - 07:21 PM

View PostYoRyan, 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


#4 User is offline   SD45T-2 

  • Engineer
  • Group: Status: Active Member
  • Posts: 667
  • Joined: 28-November 08
  • Gender:Male
  • Location:Louisiana
  • Simulator:OR, Trainz, and Misc. Sims.
  • Country:

Posted 08 May 2020 - 07:22 PM

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.

#5 User is offline   YoRyan 

  • Hostler
  • Group: Status: Active Member
  • Posts: 92
  • Joined: 19-February 20
  • Gender:Male
  • Simulator:Open Rails - testing
  • Country:

Posted 08 May 2020 - 11:45 PM

View PostR 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.

View PostSD45T-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.

#6 User is offline   eugenR 

  • Conductor
  • Group: Status: Active Member
  • Posts: 421
  • Joined: 15-April 13
  • Gender:Male
  • Simulator:MSTS
  • Country:

Posted 09 May 2020 - 03:37 AM

View PostSD45T-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

#7 User is offline   R H Steele 

  • Vice President
  • PipPipPipPipPipPipPipPip
  • Group: ET Admin
  • Posts: 2,488
  • Joined: 14-March 13
  • Gender:Male
  • Location:known universe
  • Simulator:Open Rails
  • Country:

Posted 09 May 2020 - 06:55 AM

View PostYoRyan, 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

#8 User is offline   mrmosky 

  • Conductor
  • Group: Status: Active Member
  • Posts: 327
  • Joined: 02-October 16
  • Gender:Male
  • Location:Chasetown
  • Simulator:Openrails
  • Country:

Posted 09 May 2020 - 09:15 AM

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

#9 User is offline   cjakeman 

  • Superintendant
  • PipPipPipPipPipPipPip
  • Group: ET Admin
  • Posts: 1,931
  • Joined: 03-May 11
  • Gender:Male
  • Location:Peterborough, UK
  • Simulator:Open Rails
  • Country:

Posted 09 May 2020 - 09:39 AM

View Postmrmosky, 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?

#10 User is offline   SD45T-2 

  • Engineer
  • Group: Status: Active Member
  • Posts: 667
  • Joined: 28-November 08
  • Gender:Male
  • Location:Louisiana
  • Simulator:OR, Trainz, and Misc. Sims.
  • Country:

Posted 09 May 2020 - 05:30 PM

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

  • 2 Pages +
  • 1
  • 2
  • You cannot start a new topic
  • You cannot reply to this topic

1 User(s) are reading this topic
0 members, 1 guests, 0 anonymous users