[No Squash] Use .md extension for markdown files

[rubenwardy]

This renames documention files to .md, including lua_api.txt -> lua_api.md.

FAQ

Why?

Because they're markdown files. Using the correct extension allows GitHub and editors to show syntax highlighting and render the markdown nicely.

It also allows anchor links to work

But what about line numbers?

Linking to line numbers is very brittle, and should be discouraged in favour of anchor links where possible. Linking to sections/headings is much better when it comes to keeping links alive. We should make sure to add more subheadings to make it easier to link to the correct section.

If you still want to link to a line number, you can append ?plain=1 to GitHub's URL, ex: https://github.com/rubenwardy/minetest/blob/md/doc/lua_api.md?plain=1#L123 This is a new feature, added since this was last discussed.

What about Windows users?

What's a Windows user?

Most of the documentation online links to the GitHub web version. Being able to open text files is a fairly important skill, and something that will be needed to edit eg: .conf and .lua files.

What about broken links?

I've added a stub lua_api.txt file to link to the new .md file. As for line numbers, they break regularly between releases anyway

To do

This PR is Ready for Review

How to test

View it: https://github.com/rubenwardy/minetest/blob/md/doc/lua_api.md

[appgurueu]

This will lead to merge conflicts in practically all PRs. Also:

Linking to line numbers is very brittle, and should be discouraged. Linking to sections/headings is much better when it comes to keeping links alive. We should make sure to add more subheadings to make it easier to link to the correct section.

Disagreed. You need to be able to link to a specific line - not every function can have its own section. To make the links less "brittle" you should use GitHub permalinks for this (this is no reason not to use the proper file extension though as ?plain exists).

[rubenwardy]

This will lead to merge conflicts in practically all PRs

Git can handle renaming files. The file's content has not changed

this is no reason not to use the proper file extension though as ?plain exists

Exactly

[sfan5]

How it looks: https://github.com/rubenwardy/minetest/blob/md/doc/lua_api.md

[appgurueu]

I've tested this using #12388 by making a PR against rubenwardy's md branch and indeed I am getting a merge conflict for lua_api.txt.

[rubenwardy]

I've tested this using #12388 by making a PR against rubenwardy's md branch and indeed I am getting a merge conflict for lua_api.txt.

This only happens because I readded the lua_api.txt file with a link to the new file. If I remove that commit (and lua_api.txt completely), Git does handle the rename correctly

A way around this would be to rebase on top of the first commit before the second commit

git fetch upstream

# Rebase to rename commit
git rebase --onto 051cd5ca7a13f8fea9fbb791405a55f85b208bc9 $(git merge-base upstream/master HEAD)

# Rebase to master
git pull --rebase upstream master

I can confirm that this works with your PR (although, replace upstream and upstream/master with ruben/md)

[Desour]

(Imho plain text is prettier and easier to read (and write).)

While you are at renaming the file, why not give it a more suitable name, i.e. something like server_modding_api.md. After all, there are many things in there that have nothing to do with lua.
(Properly splitting the file into its topics would be even better...)

[Zughy]

I must say, I agree with @Desour . It's way too spread, focusing is harder

But that's a GitHub issue, because the same document on GitLab looks like this:

[ghost]

Good idea.

[Zughy]

I've actually changed my mind: I think, since these documents are just for modders, info are faster to gather with plain text formats (Ctrl+F). For tutorials and the like we already have the modding book and the minetest docs repo.
I do agree that .md format makes linking stable, but in more than 2 years of modding it's never occurred to me to have to link a specific section rather than one function (and if that was the case, I just linked the modding book chapter)

[rubenwardy]

(Imho plain text is prettier and easier to read (and write).)

It's still a text document, this PR doesn't make it binary. It just gives it the correct file extension. The styling also depends on the CSS, and is subjective - I find the markdown previewer prettier than the GitHub code view

Zughy

The fact is that the file extension is just wrong. It's a markdown document with a .txt extension, it makes no sense. It's super easy to change to code view in GitHub, that should be done rather than using the wrong file extension

Also, you can still Ctrl+F in a markdown document

---

I'll just point out again that it allows you to use anchor links. If a section mentions Object properties, for example, it can link to it.

GitHub will also show a table of contents. This will make it a lot easier to navigate the document

[Zughy]

sfan5's take: https://irc.minetest.net/minetest-dev/2022-08-28#i_6010987
x2048's take: https://irc.minetest.net/minetest-dev/2022-08-28#i_6010995

[SmallJoker]

Markdown rendering could be more appealing to modders, so I am not opposed to this change.

Is it possible to prepend some CSS to control the line spacing to fix up GItHub's shortcomings? That would solve the last concern that I'd have.

[kwolekr]

👍

[Abdou-31]

You missed ^ spec = SimpleSoundSpec (see lua-api.txt) , in doc/menu_lua_api.txt, line 79.
In #12882 , I've fixed that to lua_api.txt.

[rubenwardy]

To rebase other PRs without conflicts:

git remote add upstream https://github.com/minetest/minetest

git fetch upstream
git rebase --onto b1786e88ac8921d9c4f0cfe366fdf7e2c965984c $(git merge-base HEAD upstream/master)
git pull --rebase upstream master