A useful take on web-documentation for Minetest

Post Reply
User avatar
Wizard Of mkdir
Member
Posts: 26
Joined: Tue Aug 17, 2021 14:18
GitHub: wizardofgcc
In-game: Wizard Of mkdir

A useful take on web-documentation for Minetest

by Wizard Of mkdir » Post

I recently discovered this page that presents the regular documentation text file in a much better way, with searching, good navigation and eye candy. I don't know if pretty much everyone already uses it, but it is barely publicized anywhere, so I just want to inform everyone about it. Super useful for everyone, but especially beginners since it's easy to find anything, unlike in the text file.

Link: https://minetest.gitlab.io/minetest/

LordPhyre
Member
Posts: 41
Joined: Wed Nov 17, 2021 13:01

Re: A useful take on web-documentation for Minetest

by LordPhyre » Post

Yea I've seen it, but lost the link for it.
Thanks for reminding me, this should definitely be advertised more.

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

Re: A useful take on web-documentation for Minetest

by Blockhead » Post

Can you elaborate on what this does for you over the plain text format? I find Ctrl-F (actually / in vim) to work pretty well for finding stuff in the Lua API reference. A search engine type results page is just a chore to click through, whereas a continuous file shows me where I'm up to and it's not hard to find the heading. This is fragmented across multiple files and I either need to use the internet to access it or install the tooling to build my own copy.
/˳˳_˳˳]_[˳˳_˳˳]_[˳˳_˳˳\ Advtrains enthusiast | My map: Noah's Railyard | My Content on ContentDB ✝️♂

bzt
Member
Posts: 217
Joined: Tue Sep 24, 2019 14:26

Re: A useful take on web-documentation for Minetest

by bzt » Post

Just eye-candy. The newer generations have a distaste for easy-to-use plain text files in general. To my experience, they are afraid of the highly effective command line too. (I do not want to offend anybody, this is just how things are.)

Cheers,
bzt

User avatar
philipbenr
Member
Posts: 1897
Joined: Fri Jun 14, 2013 01:56
GitHub: philipbenr
IRC: philipbenr
In-game: robinspi
Location: United States

Re: A useful take on web-documentation for Minetest

by philipbenr » Post

bzt wrote:
Wed Nov 24, 2021 14:21
To my experience, they are afraid of the highly effective command line too. (I do not want to offend anybody, this is just how things are.)
Let me correct that misconception:

Nobody wants to learn a complicated tool (command line) when they already have grown up using a much simpler, adequate, lower learning curve tool (web browser, file explorers, etc.) It has nothing to do with being afraid. It has everything to do with what is easier AND has a lower learning curve. Path of least resistance. Sure, people may be gated by the inefficiency of these easier methods at the highest end of machine mastery, but most people are not at the highest end of power users and don't need to be.

The offense that I mostly take doesn't come from the "superiority of command line users". I understand command line is superior, and I know how to use it to a higher level of proficiency then most other user interfaces. The offense I take is when people refuse to understand the standpoint of others and misconstrue them as afraid or haters or whatnot. This is one of the annoyingly fixable reasons why the open source / Linux community is seen as assholes or elitists.

---

A well advertised web-documentation for Minetest would lower the barrier of entry to those younger people who are used to online documentations and search engine tooling (e.g. Google search modifiers, borking, etc.). Many of the largest open source projects out there right now have good web documentations (e.g. VueJS, Flutter, VSCode, TensorFlow, etc.) and so I think Minetest should follow this example and have a respectable, publicized online documentation, like the one in the OP's link.

User avatar
celeron55
Administrator
Posts: 532
Joined: Tue Apr 19, 2011 10:10
GitHub: celeron55
IRC: celeron55

Re: A useful take on web-documentation for Minetest

by celeron55 » Post

Currently, for modding information, minetest.net will make you go to the devwiki, and the devwiki links to https://minetest.gitlab.io/minetest/ on multiple pages, for example https://dev.minetest.net/Modding_Intro and https://dev.minetest.net/Lua_API_Documentation.

It would be nice for a couple of people to review whether this seems adequate or if there is a path some people take, looking for API information, which does not offer them this link.

User avatar
MisterE
Member
Posts: 693
Joined: Sun Feb 16, 2020 21:06
GitHub: MisterE123
IRC: MisterE
In-game: MisterE

Re: A useful take on web-documentation for Minetest

by MisterE » Post

when I look for api information I always just search google: 'minetest api' and it gives me the gitlab site.

also I use the api file too lol

however, I usually don't think that the api is sufficient. I need short examples of how to use the code, like the dev wiki had (still has, but now its outdated and doesnt display code block properly) that is what is most useful to me, as I can copy in the snippets and adapt it to my needs

LordPhyre
Member
Posts: 41
Joined: Wed Nov 17, 2021 13:01

Re: A useful take on web-documentation for Minetest

by LordPhyre » Post

MisterE wrote:
Sun Dec 05, 2021 13:32
however, I usually don't think that the api is sufficient. I need short examples of how to use the code, like the dev wiki had (still has, but now its outdated and doesnt display code block properly) that is what is most useful to me, as I can copy in the snippets and adapt it to my needs
Same here. 100% agreed. Code snippets are the lifeforce of my modding work.
It would really be nice to have them along side the API, instead of scattered in random mods that other people made.

bzt
Member
Posts: 217
Joined: Tue Sep 24, 2019 14:26

Re: A useful take on web-documentation for Minetest

by bzt » Post

philipbenr wrote:
Wed Nov 24, 2021 17:59
Nobody wants to learn a complicated tool (command line) when they already have grown up using a much simpler, adequate, lower learning curve tool (web browser, file explorers, etc.) It has nothing to do with being afraid.
You are a perfect example of being afraid. You call command line "complicated" (while it is not complicated at all, as a matter of fact it is MUCH simpler than any GUI).

And another misconception is that GUIs are simpler. Yeah, only if you are a manual slave staring at a screen clicking with your full focus. But what if you want to make the machine do things for you in a batch (and that's what computers are for after all)? In that case GUIs are extremely problematic.

For example, how do you make a webbrowser download webpages in a list automatically? And the answer is, you cannot, you need manual interaction for that, a person clicking on a GUI. (On the other hand, with a command line tool like "wget", you can automate that task easily.)

Cheers,
bzt

User avatar
v-rob
Developer
Posts: 970
Joined: Thu Mar 24, 2016 03:19
GitHub: v-rob
IRC: v-rob
Location: Right behind you.

Re: A useful take on web-documentation for Minetest

by v-rob » Post

bzt wrote:
Fri Dec 24, 2021 13:01
You are a perfect example of being afraid.
Actually, philipbenr stated that he is well-versed with the command line and is speaking for other people.
You call command line "complicated" (while it is not complicated at all, as a matter of fact it is MUCH simpler than any GUI).
Simplicity is multi-faceted. Most people are visual, so seeing things laid out in a visual format and having visual ways to view and edit them is "simpler" in that regard than the functional "simplicity" of the command line.

Also consider that, while you may have no difficulty remembering commands, options, switches, and suchlike, other people don't have the same experience with memorizing cryptic commands and combinations, and neither do they want to have to look at the help over and over and over. It's actually quite easy to right-click on something and find the menu option that says "rename" or "delete". Which would be easier for your (or someone else's) grandmother to use? Right clicking and looking, or typing in "rm", "rm -rf", "mv", etc. (or "del", "rmdir /S /Q", "ren", etc.)? That's probably the simpler one.
But what if you want to make the machine do things for you in a batch (and that's what computers are for after all)? In that case GUIs are extremely problematic.
I think the majority of people use computers for web browsing, word processing, games, communication, and a digital way to store pictures, documents, and suchlike. In those cases, GUIs are perfectly capable. Most people don't need to batch rename a bunch of files or download a bunch of webpages. When I started programming for Minetest, I didn't need the command line for anything, and entirely used the GUIs you so despise. Hence, I didn't learn how to use it and used the much more accessible GUIs instead. I started learning and using the command line when I started needing it, and that wasn't for some time.
Core Developer | My Best Mods: Bridger - Slats - Stained Glass

bzt
Member
Posts: 217
Joined: Tue Sep 24, 2019 14:26

Re: A useful take on web-documentation for Minetest

by bzt » Post

v-rob wrote:
Fri Dec 24, 2021 23:15
Simplicity is multi-faceted. Most people are visual, so seeing things laid out in a visual format and having visual ways to view and edit them is "simpler" in that regard than the functional "simplicity" of the command line.
You're forgetting about auto-complete. With a single key press (TAB) you can see things laid out in a visual format.
v-rob wrote:
Fri Dec 24, 2021 23:15
Also consider that, while you may have no difficulty remembering commands, options, switches, and suchlike, other people don't have the same experience with memorizing cryptic commands and combinations, and neither do they want to have to look at the help over and over and over.
Again, auto-complete. About switches: yes, there are bad examples too (git being the worst one in this regard), but most of the commands are using exactly the same options and switches (part of the POSIX standard, and also somewhat standardized under WinNT too).
v-rob wrote:
Fri Dec 24, 2021 23:15
It's actually quite easy to right-click on something and find the menu option that says "rename" or "delete". Which would be easier for your (or someone else's) grandmother to use? Right clicking and looking, or typing in "rm", "rm -rf", "mv", etc. (or "del", "rmdir /S /Q", "ren", etc.)? That's probably the simpler one.
Now you made a perfect counter-example. I still remember when my mom first saw the WinWord ribbons. She was completely lost and helpless, she almost cried, that's how "easy" GUIs can be... (My grandmothers died long ago).

And there's a constant rant about the new Win menus and layouts too for example. Under DOS and previous Windows versions, menus and layouts were standardized, but not any more. No wonder people feel lost when GUIs are keep changing all the time for no good reason, so much for relying on your visual memory.
v-rob wrote:
Fri Dec 24, 2021 23:15
I think the majority of people use computers for web browsing, word processing, games, communication, and a digital way to store pictures, documents, and suchlike. In those cases, GUIs are perfectly capable.
That's a bad example again, because majority of people were never taught about the command line, all that they ever known was GUI. "Give a man a hammer, and he will see everything as a nail".
v-rob wrote:
Fri Dec 24, 2021 23:15
Most people don't need to batch rename a bunch of files or download a bunch of webpages.
If that were true, then why do manufacturers so hopelessly trying to automate GUIs? See Apple's Automator or Microsoft's Power Automate Desktop tool (both are terrible) and the armada of 3rd party tools that tries to solve this. And why are people asking this question over and over again? As far as I can see, this is a valid need, and there's a reason why developers are keep creating 3rd party tools to solve it.
v-rob wrote:
Fri Dec 24, 2021 23:15
When I started programming for Minetest, I didn't need the command line for anything, and entirely used the GUIs you so despise. Hence, I didn't learn how to use it and used the much more accessible GUIs instead. I started learning and using the command line when I started needing it, and that wasn't for some time.
And there, you said it yourself. If GUIs were really that great, then there shouldn't be a need for you to learn the command line. But you did! And I bet your workflow became much more effective because of it!

(BTW, I do not despise GUIs. I'm just aware of its limitations. There are things that simply does not work good with a GUI, and likewise, there are things which only work with a GUI and not with command line. It is forcing GUI on everything that I despise.)

Cheers,
bzt

bzt
Member
Posts: 217
Joined: Tue Sep 24, 2019 14:26

Re: A useful take on web-documentation for Minetest

by bzt » Post

But I went a bit off-topic, sorry.

To be on topic, you should take a look at gendoc. This is a small tool that generates self-contained, searchable, W3C valid static HTML documentation out of MarkDown files. It can automatically generate API references and syntax highlight code samples. If you like it, I'm willing to add configuration for everything that the Minetest doc needs and is missing (like Lua-specific highlight for example, or Minetest-specific syntax in md files etc.).

Cheers,
bzt

User avatar
ROllerozxa
Member
Posts: 157
Joined: Sun Apr 25, 2021 12:25
GitHub: ROllerozxa
IRC: ROllerozxa
In-game: ROllerozxa
Location: Sweden
Contact:

Re: A useful take on web-documentation for Minetest

by ROllerozxa » Post

Since a while back the HTML rendered version of the API has been moved to api.minetest.net, which is now deployed using GitHub rather than from the GitLab mirror which has had issues updating from the GitHub repository.

Post Reply

Who is online

Users browsing this forum: No registered users and 15 guests