[Mod] Advanced Trains [advtrains] [2.4.3]

User avatar
orwell
Member
Posts: 958
Joined: Wed Jun 24, 2015 18:45
GitHub: orwell96
IRC: orwell96_mt
In-game: orwell
Location: Raxacoricofallapatorius

Re: (Discussion) Rework of Speed Limit signs

by orwell » Post

yw05 wrote:
Fri Nov 05, 2021 09:33
Should I add 4 and 6 for consistency with the existing (mounted) Zs 3 signals?
Yes please. Doesn't hurt to have more speeds available.
yw05 wrote:
Fri Nov 05, 2021 09:33
My current idea is to use a table of speed restrictions and updating train.speed_restriction every step. Basically a new entry that looks something like this:

Code: Select all

speed_restrictions_t = {
	main = <speed>,	-- permanent local speed restriction
	line = <speed>,	-- line speed
	temp = <speed>,	-- temporary local speed restriction
}
Yes, this sounds like a reasonable idea. This would also make the code more modular.
yw05 wrote:
Fri Nov 05, 2021 09:33
Also: which category should the PSR rail fall into?
The PSR/TSR rail is out of scope, because it is never considered as speed restriction at all.
The speed restriction system has two steps: In approach (step 1, before passing the signal) the LZB subsystem is used, and in effect (step 2, after passing the signal) the speed restriction is applied. Step 2 is not applicable for the TSR rail, though the speed_restrictions_t would only be used for step 2.
Actually the LZB does not need to know about the exact category of speed restriction it is applying.

================
@56independent:
It is nice that you show interest in improving advtrains and want to help us. But please understand that it is a big project and the code is not easy to overlook. In the professional world, the developers would spend quite a lot of time writing documentation for their code, so that it is graspable for new people starting to work on it. Unfortunately Minetest is not a company that pays me to write documentation - so I simply try to avoid it. Its human nature.

So, your only chance is to try to understand the project by yourself to get a grasp of it. gpcf, ywang and the like have gone through the same process. If you want to start contributing to advtrains, then I suggest you to start working on the edge. This can be for example:
- Use the Ks signal system as a template to implement a signalling system from your home country. For this you only need to understand the signal API and there is already an example.
- http://bugs.linux-forks.de/advtrains/165.html - Doing parts of this should not be too difficult, you just need to find the correct function calls to check which train is on a certain track, the rest is inventory manipulation and copy-pasting from pipeworks/techpack
- http://bugs.linux-forks.de/advtrains/105.html would be nice to have - it's just fiddling with the player checks

Try to start on something like this. If you have a specific question then (aka "how can I find out the train ID of a train that is standing at position X?") you can contact me or the mailing list.

If at one point in time you decide to make a fork of advtrains, I have no objections. It is your right to do so.

Regarding your server and new_ks: I agree with ywang there. new_ks is a feature branch, a branch that is used for a WIP implementation of something. Although the features it implements are promising, you should not expect from a feature branch that it will be merged in a backwards-compatible manner. This is not just our humble opinion, but agreed standard in the software world.

I must admit that I do not always follow good software development practices, for example I often commit stuff directly to master - but I try to keep up a good baseline, for example that code on the master branch is always working and in most cases backwards-compatible. I try my best to achieve backwards-compatibility for official mod releases (on contentdb) though.

I hope this answers your questions.
Lua is great!
List of my mods
I like singing. I like dancing. I like ... niyummm...

yw05
Member
Posts: 366
Joined: Tue May 07, 2019 12:59
GitHub: y5nw
IRC: y5nw
In-game: ywang
Location: Germany

Re: (Discussion) Rework of Speed Limit signs

by yw05 » Post

56independent_actual wrote:
Fri Nov 05, 2021 17:58
I have removed distant signaling because it is way to (too) complicated. It will be implemented when someone figures out how to do it properly.

Does "current signaling" refer to the signaling mechanism in the master branch? That will obviously not be removed.
I mean speed limit signalling for the track ahead by "current signalling". I hope the removal of distant signalling nods to real life, like an error message on all distant speed signals for "distant speed not found due to missing code" or equivelent.
Distant signaling has been removed. Currently the signals would (by default) assume that the distant signal shows Hp 0 (halt). You can change the distant signal aspect in the route though, which needs to be fixed.
To start with, you should not run a production server off a feature branch for obvious reasons (things being unstable or broken). Use feature branches on a testing server instead - if you mess up anything, you can simply copy data over from the production server or from a backup.
Oh, that makes sense. I am a stupid sysadmin. But i did really want those features, and I regularly use them on my server. I never knew it was for testing; i merely thought it was a good idea and featureset, one i loved.
I will not (and can not) stop you if you want to maintain a patchset with the features you want.
This is the purpose of the "big read" (in tiddlywiki markup). It will help me to understand advtrains.
Have fun.
I will also be able to use my server to test features on an enterprise scale, and this is why the merge would be a good idea.
I do not see why you need the feature branch to be merged to test it. You can run the branch on a test server, and having the branch merged upstream usually means that it is stable enough, especially considering that unittests and test worlds will be set up in a way that trivial bugs will most likely be fixed before the branch gets merged.
IMO what we need that benefits advtrains is that the ideas/requests are implemented and (hopefully) unittests for more parts of advtrains get written, which is not implied by the number of people writing code for a project (although I do have to say that the example I chose is a bit extreme - so far we have not really had problems with people trying to inject malicious code into advtrains, at least as far as I am aware of(!))
The HSF will help with that. If we refer to my todo list, you can see that there are lots of changes for me to do and these will help expand my experience. I would be happy to change advtrains for the better, maybe with other devs copying some good code from HSF, or i find a bug and fix it.
Only if it was that easy ... (again, have fun)

User avatar
56independent_actual
Member
Posts: 452
Joined: Sun May 23, 2021 16:10
IRC: independent56
In-game: 56independent
Location: Girona Province
Contact:

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by 56independent_actual » Post

Note: Your post has appeared twice. This is most likely a bug with the code (thank god Minetest mods are written in Lua and not PHP).
orwell wrote:
Fri Nov 05, 2021 19:13
@56independent:
It is nice that you show interest in improving advtrains and want to help us. But please understand that it is a big project and the code is not easy to overlook. In the professional world, the developers would spend quite a lot of time writing documentation for their code, so that it is graspable for new people starting to work on it. Unfortunately Minetest is not a company that pays me to write documentation - so I simply try to avoid it. Its human nature.
What do you mean by "overlook"? Skip parts of it to find what is relevant?
So, your only chance is to try to understand the project by yourself to get a grasp of it. gpcf, ywang and the like have gone through the same process. If you want to start contributing to advtrains, then I suggest you to start working on the edge. This can be for example:
  • [item] Use the Ks signal system as a template to implement a signalling system from your home country. For this you only need to understand the signal API and there is already an example.
    [item] http://bugs.linux-forks.de/advtrains/165.html - Doing parts of this should not be too difficult, you just need to find the correct function calls to check which train is on a certain track, the rest is inventory manipulation and copy-pasting from pipeworks/techpack
    [item] http://bugs.linux-forks.de/advtrains/105.html would be nice to have - it's just fiddling with the player checks
Good ideas, but i feel that the HSF is the best way to go. I will be motivated to do this, and it is important for server politics and marketing.
Regarding your server and new_ks: I agree with ywang there. new_ks is a feature branch, a branch that is used for a WIP implementation of something. Although the features it implements are promising, you should not expect from a feature branch that it will be merged in a backwards-compatible manner. This is not just our humble opinion, but agreed standard in the software world.
My server's network will break without these features. If i want to go to the stable branch, there need be backwards compatibility to ensure my network does not crash and burn.
Last edited by 56independent_actual on Fri Nov 05, 2021 20:21, edited 1 time in total.
Warnig: Al my laguage ekscept English is bad, includig Hungarian (magyàränoлиски), Spanish (esпagnyoл), and Russian (рÿсскïанöл).

User avatar
56independent_actual
Member
Posts: 452
Joined: Sun May 23, 2021 16:10
IRC: independent56
In-game: 56independent
Location: Girona Province
Contact:

Re: (Discussion) Rework of Speed Limit signs

by 56independent_actual » Post

yw05 wrote:
Fri Nov 05, 2021 19:17
Have fun.
I do hope you mean this sarcastically, as wading through a large codebase is no easy task. The lack of an explanation mark and the directness of a full stop also communicate sarcasim.
Only if it was that easy ... (again, have fun)
I hope you are referring to the feature sharing part. Maybe it will be difficult. If it is, ha! HSF will be superior to advtrains :-p. Whenever someone commits to advtrains, i might as well adapt their change and make it resonate through HSF.
Warnig: Al my laguage ekscept English is bad, includig Hungarian (magyàränoлиски), Spanish (esпagnyoл), and Russian (рÿсскïанöл).

User avatar
orwell
Member
Posts: 958
Joined: Wed Jun 24, 2015 18:45
GitHub: orwell96
IRC: orwell96_mt
In-game: orwell
Location: Raxacoricofallapatorius

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by orwell » Post

56independent_actual wrote:
Fri Nov 05, 2021 19:35
What do you mean by "overlook"? Skip parts of it to find what is relevant.
This happens when a German tries to write English. I mean https://www.linguee.de/deutsch-englisch ... icken.html
Lua is great!
List of my mods
I like singing. I like dancing. I like ... niyummm...

User avatar
56independent_actual
Member
Posts: 452
Joined: Sun May 23, 2021 16:10
IRC: independent56
In-game: 56independent
Location: Girona Province
Contact:

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by 56independent_actual » Post

orwell wrote:
Fri Nov 05, 2021 20:03
56independent_actual wrote:
Fri Nov 05, 2021 19:35
What do you mean by "overlook"? Skip parts of it to find what is relevant.
This happens when a German tries to write English. I mean https://www.linguee.de/deutsch-englisch ... icken.html
Ahaha, thanks. I am trying to learn other languages, and i can see how the problem would be the same. English is a hard language, like German to English speakers. I am lucky i am a native so i don't have to learn such a inconsistent, broken language.

The world/phrase you were looking for was "see the big picture" (taken from my good friend Wiktionary, as my connection seems to be biased against your website). You could have also used "get an overview", using much more of the original phrase.
Warnig: Al my laguage ekscept English is bad, includig Hungarian (magyàränoлиски), Spanish (esпagnyoл), and Russian (рÿсскïанöл).

yw05
Member
Posts: 366
Joined: Tue May 07, 2019 12:59
GitHub: y5nw
IRC: y5nw
In-game: ywang
Location: Germany

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by yw05 » Post

56independent_actual wrote:
Fri Nov 05, 2021 19:35
orwell wrote:
Fri Nov 05, 2021 19:13
@56independent:
It is nice that you show interest in improving advtrains and want to help us. But please understand that it is a big project and the code is not easy to overlook. In the professional world, the developers would spend quite a lot of time writing documentation for their code, so that it is graspable for new people starting to work on it. Unfortunately Minetest is not a company that pays me to write documentation - so I simply try to avoid it. Its human nature.
What do you mean by "overlook"? Skip parts of it to find what is relevant.
The problem is that it is not easy to "find what is relevant". You can accidentally break things with new features, possibly because some things that should be relevant are overlooked, or the changes are more complicated than it should be. There were a few times where new features accidentally resulted in things being broken, and, unfortunately, it will likely happen in the future.
So, your only chance is to try to understand the project by yourself to get a grasp of it. gpcf, ywang and the like have gone through the same process. If you want to start contributing to advtrains, then I suggest you to start working on the edge. This can be for example:
  • [item] Use the Ks signal system as a template to implement a signalling system from your home country. For this you only need to understand the signal API and there is already an example.
    [item] http://bugs.linux-forks.de/advtrains/165.html - Doing parts of this should not be too difficult, you just need to find the correct function calls to check which train is on a certain track, the rest is inventory manipulation and copy-pasting from pipeworks/techpack
    [item] http://bugs.linux-forks.de/advtrains/105.html would be nice to have - it's just fiddling with the player checks
Good ideas, but i feel that the HSF is the best way to go. I will be motivated to do this, and it is important for server politics and marketing.
Like I said before: have fun. (and, in reply to the other post you wrote specifically asking whether I mean is sarcastically, it is up to you to figure out the amount of sarcasm)
Regarding your server and new_ks: I agree with ywang there. new_ks is a feature branch, a branch that is used for a WIP implementation of something. Although the features it implements are promising, you should not expect from a feature branch that it will be merged in a backwards-compatible manner. This is not just our humble opinion, but agreed standard in the software world.
My server's network will break without these features. If i want to go to the stable branch, there need be backwards compatibility to ensure my network does not crash and burn.
I have partially explained it before, and I will write this again: what you are asking for is not backward compatibility. You want the program in the master branch to properly handle a setup made with a feature that has never existed in the master branch. It is the responsibility of the maintainers of various branches to ensure the compatibility of their branches with the master branch, not vice versa. The master branch is a stable base on which the branches are developed, not a collection of the branches. In many cases (which includes that of the new-ks branch), this means that you can switch from the master branch to other branches or forks, but not vice versa, so it is fully your responsibility (and not of the maintainer of the master branch or the feature branch you are using) to make sure things do not break after you switch from the branch/fork back to the master branch. In other words, if anything breaks when you switch back from the new-ks branch to the master branch, it is up to you to fix them, not orwell or me.

User avatar
56independent_actual
Member
Posts: 452
Joined: Sun May 23, 2021 16:10
IRC: independent56
In-game: 56independent
Location: Girona Province
Contact:

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by 56independent_actual » Post

yw05 wrote:
Fri Nov 05, 2021 20:20
The problem is that it is not easy to "find what is relevant". You can accidentally break things with new features, possibly because some things that should be relevant are overlooked, or the changes are more complicated than it should be. There were a few times where new features accidentally resulted in things being broken, and, unfortunately, it will likely happen in the future.
To clarify: I initially meant to add a question mark.

But your example is good. When i make the HSF, it will be my responsibility to fix any bugs.
Like I said before: have fun. (and, in reply to the other post you wrote specifically asking whether I mean is sarcastically, it is up to you to figure out the amount of sarcasm)
In this context, it's like a direct instruction, such as "do your work" or "write another page". I will try to have fun when possible; make funny error messages "Oops, internal LuaATC parser broke! Sorry!", add easter eggs (if you do x, you get a chat message saying "ouch" or something), and make witty comments on the code ("-- But x != c ! Ha!")
I have partially explained it before, and I will write this again: what you are asking for is not backward compatibility. You want the program in the master branch to properly handle a setup made with a feature that has never existed in the master branch. It is the responsibility of the maintainers of various branches to ensure the compatibility of their branches with the master branch, not vice versa. The master branch is a stable base on which the branches are developed, not a collection of the branches. In many cases (which includes that of the new-ks branch), this means that you can switch from the master branch to other branches or forks, but it is fully your responsibility (and not of the maintainer of the master branch or the feature branch you are using) to make sure things do not break after you switch from the branch/fork back to the master branch. In other words, if anything breaks when you switch back from the new-ks branch to the master branch, it is up to you to fix them, not orwell or me.
I understand. I might as well, as it can give me server a little edge.
Warnig: Al my laguage ekscept English is bad, includig Hungarian (magyàränoлиски), Spanish (esпagnyoл), and Russian (рÿсскïанöл).

User avatar
56independent_actual
Member
Posts: 452
Joined: Sun May 23, 2021 16:10
IRC: independent56
In-game: 56independent
Location: Girona Province
Contact:

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by 56independent_actual » Post

Could we install the Orphans Wanted plugin into the wiki? I would like to create an index of pages similar to mine at my wiki, so i know what links need to be fixed and what pages need to be made. I always enjoyed writing docs more then programming.
Warnig: Al my laguage ekscept English is bad, includig Hungarian (magyàränoлиски), Spanish (esпagnyoл), and Russian (рÿсскïанöл).

yw05
Member
Posts: 366
Joined: Tue May 07, 2019 12:59
GitHub: y5nw
IRC: y5nw
In-game: ywang
Location: Germany

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by yw05 » Post

Personally, I would simply move most of the developer's reference (except for the proposals) and part of the user guide into the advtrains repo (as a lot of these may change depending on the specific branch) and generate the text using something like Sphinx. The rest of the wiki can (IMO) be replaced by the mailing lists or a dedicated asset repo with e.g. the train catalog.
Last edited by yw05 on Fri Nov 05, 2021 23:24, edited 2 times in total.

User avatar
56independent_actual
Member
Posts: 452
Joined: Sun May 23, 2021 16:10
IRC: independent56
In-game: 56independent
Location: Girona Province
Contact:

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by 56independent_actual » Post

yw05 wrote:
Fri Nov 05, 2021 23:14
Personally, I would simply move most of the developer's reference (except for the proposals) and part of the user guide into the advtrains repo (as a lot of these may change depending on the specific branch) and generate the text using something like Sphinx. The rest of the wiki can (IMO) be replaced by the mailing lists or a dedicated asset repo with e.g. the train catalog.
I have never asked on you opinions about wiki migration; i just wanted to be able to have a plugin installed so that i can make broken links green.

On an unrelated note, I want to know who operates what on what servers, just so i can understand who are the main sysadmins around Advtrains:
  • The LF (LinuxForks) wiki
  • The AdvTrains wiki
  • The mailing list
  • Bannanach space
Warnig: Al my laguage ekscept English is bad, includig Hungarian (magyàränoлиски), Spanish (esпagnyoл), and Russian (рÿсскïанöл).

yw05
Member
Posts: 366
Joined: Tue May 07, 2019 12:59
GitHub: y5nw
IRC: y5nw
In-game: ywang
Location: Germany

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by yw05 » Post

56independent_actual wrote:
Fri Nov 05, 2021 23:23
yw05 wrote:
Fri Nov 05, 2021 23:14
Personally, I would simply move most of the developer's reference (except for the proposals) and part of the user guide into the advtrains repo (as a lot of these may change depending on the specific branch) and generate the text using something like Sphinx. The rest of the wiki can (IMO) be replaced by the mailing lists or a dedicated asset repo with e.g. the train catalog.
I have never asked on you opinions about wiki migration; i just wanted to be able to have a plugin installed so that i can make broken links green.
The problem for me is how useful the current wiki is for advtrains. IMO simply adding a plugin to find broken links hardly helps, if it does anything at all.

Currently, documentation on the wiki and in the repo are out of sync - for example, you have LuaATC documentation on the repo and the wiki, and someone changing it would need to update documentation on two places or have one of them outdated. Then there are user guides which would fit well into the repo as proper documentation, except these are hosted on the wiki and not found in the repo. The result is that people waste time either updating documentation or realizing that the documentation on one of the sources is out of date.
On an unrelated note, I want to know who operates what on what servers, just so i can understand who are the main sysadmins around Advtrains:
  • The LF (LinuxForks) wiki
  • The AdvTrains wiki
  • The mailing list
  • Bannanach space
Most of these are operated by gpcf, as far as I know

User avatar
56independent_actual
Member
Posts: 452
Joined: Sun May 23, 2021 16:10
IRC: independent56
In-game: 56independent
Location: Girona Province
Contact:

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by 56independent_actual » Post

yw05 wrote:
Fri Nov 05, 2021 23:40
The problem for me is how useful the current wiki is for advtrains. IMO simply adding a plugin to find broken links hardly helps, if it does anything at all.

Currently, documentation on the wiki and in the repo are out of sync - for example, you have LuaATC documentation on the repo and the wiki, and someone changing it would need to update documentation on two places or have one of them outdated. Then there are user guides which would fit well into the repo as proper documentation, except these are hosted on the wiki and not found in the repo. The result is that people waste time either updating documentation or realizing that the documentation on one of the sources is out of date.
In that case, i belive removing docs from the repo entirely is a better solution; the Advtrains wiki should be the difinitive resource for docs. It is specifically designed for docs, and git is designed for programming. To merge the docs and the Advtrains repo would go against this huge project. Think of Python. Its docs are not part of the compiler source; they are seperate. I belive a wiki is the best way to do things. Easy editing for all.

Wikis go forward in steps, source code in leaps.
Most of these are operated by gpcf, as far as I know
Knowing what happened on a seperate website operated by him (and some ends are still yet untied), i better continuing backing up.
Warnig: Al my laguage ekscept English is bad, includig Hungarian (magyàränoлиски), Spanish (esпagnyoл), and Russian (рÿсскïанöл).

yw05
Member
Posts: 366
Joined: Tue May 07, 2019 12:59
GitHub: y5nw
IRC: y5nw
In-game: ywang
Location: Germany

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by yw05 » Post

56independent_actual wrote:
Fri Nov 05, 2021 23:48
yw05 wrote:
Fri Nov 05, 2021 23:40
The problem for me is how useful the current wiki is for advtrains. IMO simply adding a plugin to find broken links hardly helps, if it does anything at all.

Currently, documentation on the wiki and in the repo are out of sync - for example, you have LuaATC documentation on the repo and the wiki, and someone changing it would need to update documentation on two places or have one of them outdated. Then there are user guides which would fit well into the repo as proper documentation, except these are hosted on the wiki and not found in the repo. The result is that people waste time either updating documentation or realizing that the documentation on one of the sources is out of date.
In that case, i belive removing docs from the repo entirely is a better solution; the Advtrains wiki should be the difinitive resource for docs. It is specifically designed for docs, and git is designed for programming.

To merge the docs and the Advtrains repo would go against this huge project. Think of Python. Its docs are not part of the compiler source; they are seperate. I belive a wiki is the best way to do things. Easy editing for all.
I am quite sure you did not do enough research on the example you mentioned.

I do not propose embedding documentation into the source files. In the case of Python, the documentation files are separate from the source files, but still part of the repository, which is what I do propose (and to an extend, expect). This has the advantage that you can always trace an arbitrary revision of the documentation to its corresponding code, and vice versa. In comparison, having these documentation on the wiki means that you either document the software at a specific version and ignore most other things, or make the page a mess because the wiki needs to keep track of multiple different versions or branches.

Wikis are not specifically designed for software documentation, which is why projects like Doxygen and Sphinx exist at all. Git is not specifically designed only for code either, as it is not rare for projects to have documentation pages in their source repositories.

You also did not elaborate on "to merge the docs and the advtrains repo would go against this huge project", which is something I sort of expected. How (and why) does merging documentation and the advtrains repo go against advtrains?

meise21
Member
Posts: 30
Joined: Sun Feb 03, 2019 13:33

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by meise21 » Post

Forget it guys I just noticed what we messed up.

There are to similar looking tracks
- ATC controller
and
- LuaAutomation ATC Rail

They seem to look the same and somehow I started building the wrong one.... :-)
Everything working now!
Spoiler
Hi,
Today I noticed that in our main world we somehow messed up the environment configuration of the LuaATC components. Before I could right click on a ATC controller rail and configure the environment of the rail in a drop down menu where all my environments were listed. Underneath there was a text area where I could add code to the ATC controller.
ATC_rail_right_click_with_environment_selction.png
ATC_rail_right_click_with_environment_selction.png (41.58 KiB) Viewed 1890 times
But for whatever reason now that dialog has changed I can only enter a command in a single line and the environment selection drop down is missing.
ATC_rail_right_click.png
ATC_rail_right_click.png (15.06 KiB) Viewed 1890 times
I assume the ATC controllers I place now are not assigned to the right environment and therefore they are unable to call the functions I added to F in the init code of my environment. This then results in error "661272 ATC command parse error: Unkown command: F.foo()" when a train goes over the rail.

In a new clean world I could:
1. create an environment
2. add a function foo to the init block
3. build an ATC controller rail
4. asign it to my environment and add a function call to foo
5. let the train run over it

Any help on why it is different in our main world appreciated!

User avatar
Blockhead
Member
Posts: 1602
Joined: Wed Jul 17, 2019 10:14
GitHub: Montandalar
IRC: Blockhead256
In-game: Blockhead Blockhead256
Location: Land Down Under
Contact:

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by Blockhead » Post

meise21 wrote:
Sat Nov 06, 2021 07:56
Forget it guys I just noticed what we messed up.

There are to similar looking tracks
- ATC controller
and
- LuaAutomation ATC Rail
This is a good reminder that they should have different textures :)
/˳˳_˳˳]_[˳˳_˳˳]_[˳˳_˳˳\ Advtrains enthusiast | My map: Noah's Railyard | My Content on ContentDB ✝️♂

User avatar
Blockhead
Member
Posts: 1602
Joined: Wed Jul 17, 2019 10:14
GitHub: Montandalar
IRC: Blockhead256
In-game: Blockhead Blockhead256
Location: Land Down Under
Contact:

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by Blockhead » Post

56independent_actual wrote:
Fri Nov 05, 2021 23:48
In that case, i belive removing docs from the repo entirely is a better solution; the Advtrains wiki should be the difinitive resource for docs.
On the contrary, the wiki DokuWiki source text should be included in a repo (perhaps the main repo, perhaps a separate one with just the docs, or a submodule that can be optionally checked out) along with instructions on how to run it locally. People have a right to be able to use the software offline (ref). The wiki's images can be made available through git lfs so that the download size isn't ballooned out of proportion. Then we can include instructions on how to run your copy of the wiki locally.

DokuWiki's syntax is readable in a text editor, so as long as we write the wiki to not depend too heavily on images and include alt text/image captions, it will not end up too different to the existing markdown/plain text format documentation we have on AdvTrains.

By doing it this way we will solve the issue of the docs being out of date with the wiki and remove the need to be connected to the internet to get the full docs. At the same time, if properly maintained then the history of the wiki will accurately reflect the history of advtrains and give you accurate docs in case you are checking out an older version of the program.

To achieve this end I'll need to be in contact with gpcf/orwell to make sure we can get those wiki files out of the DokuWiki server filesystem into a git repository. From there it's a simple project to work out how to fit them into the advtrains distribution and how to read a local copy of the wiki.
/˳˳_˳˳]_[˳˳_˳˳]_[˳˳_˳˳\ Advtrains enthusiast | My map: Noah's Railyard | My Content on ContentDB ✝️♂

User avatar
56independent_actual
Member
Posts: 452
Joined: Sun May 23, 2021 16:10
IRC: independent56
In-game: 56independent
Location: Girona Province
Contact:

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by 56independent_actual » Post

Blockhead wrote:
Sat Nov 06, 2021 08:05
This is a good reminder that they should have different textures :)
As i wrote in the mailing list, but since i am going to be a dev anyways, i have changed the texture:
advtrains_dtrack_shared_luaatc.png
advtrains_dtrack_shared_luaatc.png (18.59 KiB) Viewed 1890 times
It is now magenta, but i would like another developer to go through the process of making a patch with my new texture inside.
Warnig: Al my laguage ekscept English is bad, includig Hungarian (magyàränoлиски), Spanish (esпagnyoл), and Russian (рÿсскïанöл).

User avatar
56independent_actual
Member
Posts: 452
Joined: Sun May 23, 2021 16:10
IRC: independent56
In-game: 56independent
Location: Girona Province
Contact:

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by 56independent_actual » Post

Blockhead wrote:
Sat Nov 06, 2021 08:06
On the contrary, the wiki DokuWiki source text should be included in a repo (perhaps the main repo, perhaps a separate one with just the docs, or a submodule that can be optionally checked out) along with instructions on how to run it locally. People have a right to be able to use the software offline (ref). The wiki's images can be made available through git lfs so that the download size isn't ballooned out of proportion. Then we can include instructions on how to run your copy of the wiki locally.
Great idea! I personally feel that all articles on the wiki should be the main articles, and using crontab, you can use SCP (if the wiki and repo are on seperate servers) to copy the dokwiki/data/pages directory over every interval of time (i reccomend a week). Or crontab could just use git. Maybe i should hold a git repo on my server, for my wiki, as a proof of concept. I would be happy to do so.
Warnig: Al my laguage ekscept English is bad, includig Hungarian (magyàränoлиски), Spanish (esпagnyoл), and Russian (рÿсскïанöл).

User avatar
56independent_actual
Member
Posts: 452
Joined: Sun May 23, 2021 16:10
IRC: independent56
In-game: 56independent
Location: Girona Province
Contact:

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by 56independent_actual » Post

yw05 wrote:
Sat Nov 06, 2021 00:39
I am quite sure you did not do enough research on the example you mentioned.

I do not propose embedding documentation into the source files. In the case of Python, the documentation files are separate from the source files, but still part of the repository, which is what I do propose (and to an extend, expect). This has the advantage that you can always trace an arbitrary revision of the documentation to its corresponding code, and vice versa. In comparison, having these documentation on the wiki means that you either document the software at a specific version and ignore most other things, or make the page a mess because the wiki needs to keep track of multiple different versions or branches.

Wikis are not specifically designed for software documentation, which is why projects like Doxygen and Sphinx exist at all. Git is not specifically designed only for code either, as it is not rare for projects to have documentation pages in their source repositories.

You also did not elaborate on "to merge the docs and the advtrains repo would go against this huge project", which is something I sort of expected. How (and why) does merging documentation and the advtrains repo go against advtrains?
I'm sorry. I was getting gradually more tired as the night went on, and my brain began to lapse concentration. I have found Blockhead's idea great - taking the wiki source and updating Advtrains docs from the wiki's data/pages directory. I am not talking about docs for the code, but the finished product.

As for my quote? I wrote it far too tired (people made "don't drive when tired", and "don't drink when tired", I suggest "don't post when tired"). What i meant was that to have a docs folder in the advtrains repo would be a bad idea as documentation changes and source code changes both end up in the same commit log. I suggest an alternate repo, where to edit, you may use the wiki, or change the rope files (may require complex synchronisation).

Your "i sort of expected" was far too ambiguous. What did you expect? An elaboration? A lack of one?
Warnig: Al my laguage ekscept English is bad, includig Hungarian (magyàränoлиски), Spanish (esпagnyoл), and Russian (рÿсскïанöл).

yw05
Member
Posts: 366
Joined: Tue May 07, 2019 12:59
GitHub: y5nw
IRC: y5nw
In-game: ywang
Location: Germany

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by yw05 » Post

I have implemented most things that need to be done for the new-ks branch. Here is a screenshot of the new/modified nodes so far:

Image

(Refer to orwell's excellent post for an explanation of these signal signs.)

Currently a few minor bugs still need to be fixed, but the branch should be stable now.

I have created a test world for the signal signs using the patch from the luaatcdebug branch. Tests for the mounted Zs 3(v) indicators will follow. You can test it with the branch applied on top of the new-ks branch: git format-patch --stdout luaatcdebug~1..luaatcdebug | git am - (DEFINITELY don't run a server off the luaatcdebug branch)

Notes regarding the signal signs
  • Existing speed signal signs from the master branch are automatically converted to Zs 3 signs (they have the same item string - only the models and textures are changed). You do not need to replace them yourself.
  • The new-ks branch uses the Lf 7 nodes for line speed restriction.
  • There are now four speed sign placers:
  • The yellow and green lights on the Ks signals have been swapped to reflect the real-life Ks signal.
    • White "8" on a black background: Zs 3 signs (analogous to the current speed sign placer)
    • Black "8" on an orange background: Lf 1/2 signs
    • Black "8" on a white background: Lf 7 signs
    • Black box on a white background: Miscellaneous feature signs (Ra 10, "proceed as main" sign)
  • There are two types of Zs 3 signals: one mounted onto Ks masts (and can only be used with Ks signals, also called), and the Zs 3 signs which are used independently.
  • The train HUD is not yet updated to correctly handle the different types of speed restrictions. (Edit: done)
Attachments
advtrains_testworld.tar.gz
(431.37 KiB) Downloaded 30 times
screenshot_20211106_205228.png
screenshot_20211106_205228.png (513.55 KiB) Viewed 1890 times
Last edited by yw05 on Sun Nov 07, 2021 13:16, edited 1 time in total.

Maverick2797
Member
Posts: 128
Joined: Sun Aug 05, 2018 12:37
In-game: Maverick2797
Location: Poking about here and there...

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by Maverick2797 » Post

56independent_actual wrote:
Sat Nov 06, 2021 11:25
I have found Blockhead's idea great - taking the wiki source and updating Advtrains docs from the wiki's data/pages directory. I am not talking about docs for the code, but the finished product.
To some users the finished (is anything truly finished?) product is the code. I know I spend half my time with the LuaATC readme open while messing around with various projects as a quick reference. And that's not to mention the ever-evolving nature of open-source projects.
56independent_actual wrote: What i meant was that to have a docs folder in the advtrains repo would be a bad idea as documentation changes and source code changes both end up in the same commit log. I suggest an alternate repo, where to edit, you may use the wiki, or change the rope files (may require complex synchronisation).
Let's not make it more complicated than it needs to be... I see no reason why there shouldn't be a docs folder in the main advtrains repo. Perhaps a simple "Start Here" could be included in the root directory, a bit like the html/pdf manuals buried in the assets directory. Other than that the readme's should be relevant to their submodules. If you actually go back through the log you'll see that as features change the docs are usually incrementally updated to match. Very rarely is there a large docs-only commit, more likely is a small fix of a typo etc.
The number you have called is not available during a solar eclipse. This message will self destruct in ten seconds in protest... [BEEP]

yw05
Member
Posts: 366
Joined: Tue May 07, 2019 12:59
GitHub: y5nw
IRC: y5nw
In-game: ywang
Location: Germany

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by yw05 » Post

56independent_actual wrote:
Sat Nov 06, 2021 11:25
I have found Blockhead's idea great - taking the wiki source and updating Advtrains docs from the wiki's data/pages directory.
Then you end up spamming the source repo with "update documentation from the wiki" commits.
I am not talking about docs for the code, but the finished product.
The code is the product.
What i meant was that to have a docs folder in the advtrains repo would be a bad idea as documentation changes and source code changes both end up in the same commit log.
I am note sure why that is bad. Keeping documentation and code together is IMO necessary as it allowes you to get the documentation that is relevant to the branch/version you are using, as I have already previously wrote:
This has the advantage that you can always trace an arbitrary revision of the documentation to its corresponding code, and vice versa. In comparison, having these documentation on the wiki means that you either document the software at a specific version and ignore most other things, or make the page a mess because the wiki needs to keep track of multiple different versions or branches.
Whether the separated documentation or code is hosted on a wiki or git repo does not matter for that argument.

Your post is more or less the same as "keeping docs and code separate", which you have already wrote previously. For reference:
In that case, i belive removing docs from the repo entirely is a better solution; the Advtrains wiki should be the difinitive resource for docs. It is specifically designed for docs, and git is designed for programming. To merge the docs and the Advtrains repo would go against this huge project. Think of Python. Its docs are not part of the compiler source; they are seperate. I belive a wiki is the best way to do things. Easy editing for all.
When docs and code are separated, using git vs using a wiki is irrelevant when it comes to making documentation and code in sync.

What you have written so far boils down to "having documentation in the advtrains source repo is a bad idea and goes against the project", and so far I except you to explain why.

yw05
Member
Posts: 366
Joined: Tue May 07, 2019 12:59
GitHub: y5nw
IRC: y5nw
In-game: ywang
Location: Germany

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by yw05 » Post

As a proof of concept, I wrote some documentation on the additions of the new-ks branch in Markdown. Pandoc seems to convert them to manual pages quite well.

User avatar
56independent_actual
Member
Posts: 452
Joined: Sun May 23, 2021 16:10
IRC: independent56
In-game: 56independent
Location: Girona Province
Contact:

Re: [Mod] Advanced Trains [advtrains] [2.3.1]

by 56independent_actual » Post

yw05 wrote:
Sun Nov 07, 2021 12:33
As a proof of concept, I wrote some documentation on the additions of the new-ks branch in Markdown. Pandoc seems to convert them to manual pages quite well.
Brilliant! We might as well make a regex Dokuwiki to Markdown converter (i can write the expressions, you can tellme what needs to be converted). Or not.
Warnig: Al my laguage ekscept English is bad, includig Hungarian (magyàränoлиски), Spanish (esпagnyoл), and Russian (рÿсскïанöл).

Post Reply

Who is online

Users browsing this forum: No registered users and 10 guests