Move documentation for game to markdown format.

[red-001]

This allows GitHub to display the documentation with proper styling making it easier to read and use as a reference.
See: #798.
Link to file in markdown

[sofar]

This blows away all git history, and many lines are similar before and after

can you instead of copying, do

git mv game_api.txt game_api.md

And then incrementally fix the markup format where needed?

[red-001]

@sofar sorry about that I did do that but squashing removed it from history. Will fix soon.

[red-001]

Does that mean two commits?

[sofar]

Those 2 commits look fine to me - at least there's some coherence in what was changed, and unchanged lines are present (good).

[paramat]

rubenwardy wrote > lua_api.txt is in markdown, but hasn't been renamed for some reason

There may be a good reason for this, the document file should always be quickly and simply openable as a text document, as far as i can remember this was requested by celeron55. Our documents should always be primarily intended to be simple text documents even if they are in markdown format.

[red-001]

It's no harder to open a .md document as a text then to open a .lua as a text and minetest modding requires a lot of the second.

[paramat]

Sorry, you're probably right on that. Would opening a .md file in github display as text or MD? i prefer to see the text version. The MD version is friendlier for non-devs but devs i think prefer the real thing.

[sofar]

github automatically displays all md files as markdown, not plain text.

[rubenwardy]

But you can click "raw" to view the raw file.

[paramat]

Okay, i do remember c55 insisting on lua_api.txt remaining a txt file, and i agree, when i go to the file in github it will be irritating to need another step to see the actual text file, devs are used to it as text and want to see it like that.

[kilbith]

I prefer the good raw .txt format as well for not being polluted by script attributes and "fashion" shallowness.

[paramat]

See commit message for minetest/minetest@800d912

[rubenwardy]

Md/Html formats are much better for sharing links to, without worrying that the line number will change.

However, you could just use lua_api.html.

[red-001]

@kilbith It is perfectly readable as a text file, most of the changes made a very minor like changing a ' to a not anything major.``lua appears in the file a few times but that hardly matters to readability.

@paramat I don't think there are a lot of references to game_api.txt but that is a good point.

I guess you could always make game_api.txt say something like moved to game_api.md.

[red-001]

@rubenwardy Is that up to date with lua_api.txt?

[paramat]

I find the extra symbols hard on the eyes when viewed as text, i had just got used to lua_api.txt when it was unfortunately changed to MD format, i wish it had not been, a mistake i think. A carefully and cleanly formatted text document would be just as good, the MD format version should be maintained separately by whoever can be bothered to do that.

[rubenwardy]

Maintaing two versions is rather silly. Just learn to adapt. I am very glad it was standardised into markdown, makes linking much easier.

[paramat]

Yeah i agree 2 versions would be problematic, inevitably one would lag behind and it's more work. So it's a case of what's more important, a friendly document for modders or a a cleaner text document for devs, difficult choice. Maybe these documents could be made clearer while still being in MD format.

[paramat]

Okay with some thought, i'll support markdown format but will never support changing the file extension to .md. Markdown format is meant to be friendly but for a dev the text is preferable, more compact. After looking at lua_api.txt displayed as MD i don't find it an improvement, there's so much space between everything it's actually less clear to me.

I'll +1 this if updated to be formatting only.

[kilbith]

I find the extra symbols hard on the eyes when viewed as text

This is exactly what bother me too.

[red-001]

@paramat what do you find decrease the readability as text most?

[paramat]

Just the general overuse of special symbols, instead of beng free to make it as clear as possible.

[0-afflatus]

Markdown is for people who find HTML difficult and should only be used in circumstances where the file is not going to be read in the raw. I use text files for my READMEs without the .txt extension. This may be because I have a bad attitude towards Windows users, however.

[rubenwardy]

Markdown is for people who find HTML difficult and should only be used in circumstances where the file is not going to be read in the raw.

Urr, no.

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

https://daringfireball.net/projects/markdown/

[0-afflatus]

Point taken @rubenwardy - it just doesn't work for me.

[paramat]

The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

It fails then :)

[paramat]

I'll +1 this if updated to be formatting only, please keep it .txt.

[red-001]

@kaeza @paramat removed the ```lua.

[red-001]

@rubenwardy added extra spaces.

[paramat]

Lines 261-294 seem to have inconsistent indentations of comments and varying number of spaces after the asterisks. In these comments some parameters are within '' some are not.

I agree this is borderline non-trivial but due to elusive mtgame devs i'm happy to take the risk, we've had good input on this too from others.

[paramat]

The indentation in the dyes section is inconsistent.
In Doors API section, varying indentation of 'register new ..' text.
These don't show up when displayed as MD but look bad in the text version.

Actually this document looks okay in MD format, lua_api.txt is a little harder on the eyes due to its density.

[sofar]

The doors API patch is not yet merged, so this will conflict. I have various style fixes pending in the PR there, and will refresh that one depending on what gets merged first.

[paramat]

This may need rebasing due to fences API being added.

[sofar]

@paramat I prefer seeing patches merge quicker than attempting to choreograph a dance around dependencies, especially when it comes to documentation which shouldn't gate or be gated by anything.

[paramat]

Agreed, it may not conflict.
Inconsistencies still need editing.

[paramat]

^ @red-001

[paramat]

This may need to be worked on by someone else as the author is absent.

[red-001]

I'm back.

[paramat]

Welcome back.

[paramat]

Line 129: 'choppy = 2' please.
Lines 77, 283, 285, 290: Should be 1 space after asterisk not 2.
Lines 371 to 400: Please indent all the lines starting with asterisks by 1 more space to be consstent with the rest of the file.

[sofar]

Still needs rebasing.

[red-001]

@sofar Rebased.

[paramat]

Lines 28, 29, 37, 61: One less tab indent.
Lines 35, 36 and 50 to 58: Align comments vertically using spaces. Alignment depends on tab size so work with github's tab size of 8.
Line 83: No space after first curly bracket.
Line 103: No spaces inside curly brackets.
Line 116: Should be 'tile_side = ""'
Line 139: 'choppy = 2'

Please add the new tree function:
default.grow_new_snowy_pine_tree(pos)
'Grows a new design snowy pine tree at pos'

[paramat]

^ @red-001 Please update soon.

[red-001]

@paramat Updated.

[paramat]

👍 Will merge soon as trivial.

[paramat]

68f5740