News:

Simutrans.com Portal
Our Simutrans site. You can find everything about Simutrans from here.

Simutrans-Extended readme overhaul

Started by Roboron, February 07, 2022, 05:17:55 PM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

Roboron

Akin to the updates of Standard readme I myself pushed, the Simutrans-Extended documentation is in need of an update (particularly because newly introduced libraries and build systems are not mentioned). Now that requirements for Extended are on-par with Standard again, I have adapted the new readme to Extended, replacing Standard links and references for Extended, and adding Extended-specific information.

The purpose of this new readme is not only to give up-to-date information about compiling, but also extend it with basic information about Simutrans-Extended, how to get it, and how to contribute, specially for people reaching Simutrans-Extended through GitHub's web-interface (with the README.md variant for better formatting).

I'm not an Extended player, so there may be things you feel missing. Feel free to add them.

There are three readme's. README.md is the main one, with README.html being just a conversion. readme.txt is a short version of README.md, more appropriate to read without formatting.  I added them on different commits in case you want to leave out any of them (I do  myself think that three may be too much, and the .txt or and .md variants or even only the .md variant is enough, but Standard decided to include all of them).

Preview of the readme and pull request:

=> https://github.com/Roboron3042/simutrans-extended/tree/readme-overhaul#simutrans-extended
=> https://github.com/jamespetts/simutrans-extended/pull/491

PJMack

It looks good.  My only critique is that the source code link in Section 2.1 is to aburch's simutrans git repository rather than jamespetts' or simutrans' simutrans-extended repository. 

Roboron

**** it. Thank you for checking it, corrected.

jamespetts

Download Simutrans-Extended.

Want to help with development? See here for things to do for coding, and here for information on how to make graphics/objects.

Follow Simutrans-Extended on Facebook.

Matthew

Roboron, thank you for adding these Readme pages. I often use the state of projects' GitHub readme as an indicator of how user-friendly a project is. So hopefully this will grow the Simutrans community.

Anyway, I just tried following the Compilation instructions. They do not mention that compilation requires the usual packages like make, which is important information for total newbies. For Debian and its descendants (including Ubuntu), these are provided by the build-essential metapackage. So maybe that should be added to the dependencies.
(Signature being tested) If you enjoy playing Simutrans, then you might also enjoy watching Japan Railway Journal
Available in English and simplified Chinese
如果您喜欢玩Simutrans的话,那么说不定就想看《日本铁路之旅》(英语也有简体中文字幕)。

Roboron

I think that information is too basic to be included in the README. Indeed, the original instructions were much larger and explained the process in more detail, but it got cut out in the fear it would be too long to be read for the average developer.

Such information is much more fitting in the linked wiki page, where extra documentation about the process is more welcome. But feel free to add whatever you want to the README, I just did the port of the new README from Standard and now that it is incorporated it is no longer in my hand.

Quote from: Matthew on February 23, 2022, 05:08:22 AMI often use the state of projects' GitHub readme as an indicator of how user-friendly a project is.

That's precisely one of my motivation to do this. Although there is still the problem that simutrans-extended repository is a little too big and you have to scroll down quite a lot to reach the readme in GitHub. But hopefully this will improve when Extended adopts the code reorganization Standard did some weeks ago.