A useful take on web-documentation for Minetest
- 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
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/
Link: https://minetest.gitlab.io/minetest/
Re: A useful take on web-documentation for Minetest
Yea I've seen it, but lost the link for it.
Thanks for reminding me, this should definitely be advertised more.
Thanks for reminding me, this should definitely be advertised more.
- Blockhead
- Member
- Posts: 1688
- 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
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 ✝️♂
Re: A useful take on web-documentation for Minetest
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
Cheers,
bzt
- 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
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.
Re: A useful take on web-documentation for Minetest
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.
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.
- 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
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
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
Re: A useful take on web-documentation for Minetest
Same here. 100% agreed. Code snippets are the lifeforce of my modding work.MisterE wrote: ↑Sun Dec 05, 2021 13:32however, 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
It would really be nice to have them along side the API, instead of scattered in random mods that other people made.
Re: A useful take on web-documentation for Minetest
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).philipbenr wrote: ↑Wed Nov 24, 2021 17:59Nobody 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.
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
- v-rob
- Developer
- Posts: 971
- 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
Actually, philipbenr stated that he is well-versed with the command line and is speaking for other people.
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 call command line "complicated" (while it is not complicated at all, as a matter of fact it is MUCH simpler than any GUI).
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.
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.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.
Re: A useful take on web-documentation for Minetest
You're forgetting about auto-complete. With a single key press (TAB) you can see things laid out in a visual format.
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:15Also 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.
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).v-rob wrote: ↑Fri Dec 24, 2021 23:15It'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.
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.
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".
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.
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!v-rob wrote: ↑Fri Dec 24, 2021 23:15When 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.
(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
Re: A useful take on web-documentation for Minetest
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
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
- ROllerozxa
- Member
- Posts: 158
- 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
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.
Who is online
Users browsing this forum: No registered users and 46 guests