Time Nick Message 03:52 MTDiscord Been doing some research, I think handwritten plain old markdown is the best way to go to get started. We can use HTML tables instead of ASCII art if that's a significant concern, but overall what seems to be missing most is, well, documentation of any sort. Once we have something, we can look at migration to "better" systems. Also hi I'm Mark I'm new here and I want to improve the new engineer experience 🙂 03:54 MTDiscord Plain Markdown is just so easy to get started with. No, it won't be programmatically connected to the codebase and it won't provide autocomplete in IDEs, but it will provide clean, readable documentation that can be deployed to a simple site or even read on GitHub itself with its preview feature. 04:17 MTDiscord There has also been talk of abandoning AsciiDoc, but it looks fine to me. What are the main drawbacks? 04:25 MTDiscord Hoping we can use https://github.com/minetest/minetest_docs/issues/52 as a discussion board as well so that conversations get indexed instead of floating away in IRC 🙂 04:33 MTDiscord Warning This project is in its early stages. Don’t expect to be able to use it in anything relevant, yet From 3 years ago 😦 04:54 MTDiscord The main drawback is that it isnt markdown. I agree with your previous statement, plain (or flavored) markdown is the way to go. Processors can go on top of that. 04:55 MTDiscord Makes sense, just wanted to make sure. I've got the repo forked and cloned, I'm assuming these docs haven't been deployed to any GitHub Pages site or anything? I just need to make sure I can preview the page and I'm all caught up in terms of what this repo can do? 04:56 MTDiscord Correct 05:03 MTDiscord Just to confirm, we want to use Markdown over AsciiDoc simply because it's more popular and has more tooling supporting it? Any other reasons I'm missing? 05:05 MTDiscord The biggest reason is it's more familiar 05:05 MTDiscord AsciiDoc looks like markdown on first glance, but once you start writing it you'll realize that it very much isnt 05:05 MTDiscord I would wager the largest reason there isnt more written already is because writing in ADoc is harder than it needs to be 05:07 MTDiscord https://alvinalexander.com/bookmarks/how-convert-asciidoc-to-html-or-markdown/ 🙂 05:07 MTDiscord Yep, that did seem to be the avenue 05:08 MTDiscord Didn't see it linked earlier, figured better safe than sorry. But yeah, looks like AsciiDoc -> Docbook -> Markdown works according to this random article 05:08 MTDiscord Just to be clear, we'll probably end up using GFM in particular 05:08 MTDiscord GFM + custom macros n stuff 05:08 MTDiscord Sure, I don't have any particular preference, not too famililar with custom macros but I'm good at learning 🙂 05:09 MTDiscord The custom macros will be implemented with Pandoc 05:09 MTDiscord It supports custom Lua filters, so I already have a mustache macro thing written most of the way 05:11 MTDiscord The pipeline will eventually (probably) look something like: (LDoc from code, GFM pags) -> Pandoc -> (GFM, HTML) 05:12 MTDiscord pages* 05:16 MTDiscord I like it 🙂 05:16 MTDiscord could you provide deets on what a mustache macro is? 😄 05:16 MTDiscord {{var_name}} 05:16 MTDiscord that's the name of that syntax?? I never knew! 05:16 MTDiscord i just skimmed, are you guys switching to LaTaX? 05:16 MTDiscord To Markdown 🙂 05:16 MTDiscord Just using this guys name for it https://mustache.github.io/ 05:17 MTDiscord Pandoc supports LaTeX so if it was ever really needed it could be included 05:17 MTDiscord Especially since GFM supports arbitrary HTML 05:17 MTDiscord And they https://docs.cfengine.com/docs/3.24/resources-faq-mustache-templating.html call it mustache too 05:18 MTDiscord Yeah mustache seems to be the best name, TIL 05:18 MTDiscord templating/macros/variables whatever 05:18 MTDiscord https://en.wikipedia.org/wiki/Mustache_(template_system) 05:18 MTDiscord the non-fun name is curly braces interpolation lol 05:19 MTDiscord "Moustaches would not go away during the Middle Ages." thanks Wikipedia 😄 05:19 MTDiscord so adoc is still used for the "minetest doc project"? 05:19 MTDiscord ... did you not read? 05:19 MTDiscord Yes 05:19 MTDiscord https://discord.com/channels/369122544273588224/926231483155378176/1301776964864053269 05:20 MTDiscord Xenith and I would like to switch to plain Markdown for the Minetest doc project (this project) 05:20 MTDiscord oic 05:20 MTDiscord (s/plain/gfm/whatever) 05:20 MTDiscord why "in any way"? 05:20 MTDiscord Because it's doesn't have much ecosystem support and it "yet another documentation format" that doesn't provide enough value to justify it being different than Markdown 05:21 MTDiscord wdym ecosystem support? 05:21 MTDiscord i think it has some value to differentiate itself from markdown, as well as having okay-ish tools which let you export to other formats anyway 05:22 MTDiscord Pandoc cannot convert AsciiDoc files directly to other formats, for example. And the interpreters that we do find are in alpha and abandoned from 3 years ago. I could be wrong, I guess, but I think we can agree Markdown has TONS of high-quality tooling for sure. 05:22 MTDiscord i really just see it as markdown++ 05:22 MTDiscord AsciiDoctor should export to Docbook which i can imagine Pandoc might support 05:22 MTDiscord That's fair, I'm happy to explore both routes 05:22 MTDiscord Docbook exporting alone kind of opens a lot of doors 05:23 MTDiscord which is why i like asciidoc 05:23 MTDiscord but if you guys can find a way to cope with Markdown, go for it 05:23 MTDiscord For now, though, my goal is to get documentation written in any form, adoc, md, txt, whatever. Then we can look at which format is "best" 05:23 MTDiscord Pandoc has more options than Docbook 05:24 MTDiscord Sorry, AsciiDoctor 05:24 MTDiscord Pandoc in my own experiences is a hacked up piece of shite, really. I'm just saying that AsciiDoc supports exporting to Docbook which just opens a lot of doors to anything 05:24 MTDiscord I'm going to stop chatting and start writing now, see y'all tmrw 🙂 05:25 MTDiscord Im not super concerned about tooling anyway; I am just using Pandoc as a processor more than anything else 05:25 MTDiscord wtf a microsoft employee 05:26 MTDiscord heh 05:26 MTDiscord Sure, I think Markdown (github flavored) can do quite a lot and if you guys can get any success with that then go for it. 05:26 MTDiscord I really wish org-mode wasn't locked to Emacs, I love that shit and its a great format too 05:27 MTDiscord https://github.com/curl/everything-curl/ 05:27 MTDiscord Maybe take a look at this 05:28 MTDiscord I think my peaves with Markdown generally just lay down to how it can be too simple at times; tooling can kind of work around it though (and to a degree some may consider this a positive) 05:28 MTDiscord The things that markdown cant do, like substitution and minimal logic, are easily done with Lua filters in Pandoc 05:28 MTDiscord So pandoc does more than generate dogshit HTML pages from C++ code? 05:28 MTDiscord Which is what we originally wanted AsciiDoc for, but realized their macros are kinda bad (and require custom Ruby); That makes Pandoc a lot more appealing 05:29 MTDiscord Its conversion tooling 05:29 MTDiscord I see 05:29 MTDiscord i just have nightmares from compiling it and working with Pandoc 05:29 MTDiscord Input -> Output ... in this case, the input and output are roughly the same and I am (ab)using it as a preprocesor 05:29 MTDiscord m4 is the most powerful text preprocessor 05:30 MTDiscord :^) 05:31 MTDiscord https://cdn.discordapp.com/attachments/926231483155378176/1301780698746847233/image.png?ex=6725b940&is=672467c0&hm=95ca516bd165a5f8ba164f15fc675a824758b99bcd8548ae0e1d7e0f89d85c37& 05:31 MTDiscord wordlist.txt ? 05:33 MTDiscord but anyway, everything-curl is a nice book. I think it has the most creative approach to creating documentation; sometimes you really can get by by just making your own scripts, i.e. your own lua parsers, which might offer more control and less fiddling with Pandoc. 05:35 MTDiscord this uses mdBook. Maybe take a look at this too? 05:35 MTDiscord https://gitgud.io/swagtoy/readtheblocks/-/blob/master/mt_docs.pl?ref_type=heads 05:36 MTDiscord Here's how I made ReadTheBlocks (a half-assed clone of the Minetest docs) 05:36 MTDiscord https://swag.toys/minetest-docs/ 05:36 MTDiscord Mind, we'd also want a way to convert our markdown into pretty html 05:37 MTDiscord there's a million and then some libraries for this, I actually used some Perl library to accomplish it, and this offered granular control over how i render things/remove stuff 05:37 MTDiscord Also, how dare I forget: Machine parsing for language servers 05:37 MTDiscord like you could even do crazy stuff where you can parse a ```evallua block 05:37 MTDiscord which becomes some macro thingy 05:38 MTDiscord by simple checking each markdown thing using your API 05:38 MTDiscord Absolutely bonkers idea: iframe with minetest for the web to run snippets 05:38 MTDiscord there was actually a weird idea in my head; creating a "fake minetest" runtime environment 05:38 MTDiscord implementing a basic subset of the api, even object immitations and stuff 05:38 MTDiscord and using some web-based Lua port 05:39 MTDiscord then people could even poke at the code and mess around 05:39 MTDiscord but i dont think this would be extensive enough 05:39 MTDiscord I plan to integrate a headless minetest server into my VSC extension at some point to live test code 05:39 MTDiscord we could use a cool debugging system for this 05:39 MTDiscord Feature creeeeeeeep 05:40 MTDiscord The scarriest thing ive seen today 05:40 MTDiscord honest to God, really? Even Roblox or whatever has debugging crap 05:40 MTDiscord Nah im just saying this is all featrure creep for a docs irc channel 05:40 MTDiscord feature* 05:40 MTDiscord Oh yeah 05:41 MTDiscord Anyway, I'm personally more in favor of hand generating stuff and then either A) making your own dynamic webpages or B) just using mkDoc or something (anything BUT ReadTheDocs) 05:41 MTDiscord kinda like how https://everything.curl.dev does it 05:42 MTDiscord Not a huge fan of the common markdown-to-sidebar-html doc system. Not enough information up front, clunky to navigate 05:42 MTDiscord do you mean for my thingy? 05:42 MTDiscord or his 05:43 MTDiscord Any of them 05:43 MTDiscord im gonna slightly disagree, i mean i get where you are going, especially for a "book", but its basically just an index QoL thing 05:44 MTDiscord ReadTheDocs did a sidebar but it was awwwwwful 05:44 MTDiscord RTD requires you to click on an item (and go to the page) in the sidebar to expand it 05:44 MTDiscord Which is asinine 05:45 MTDiscord mine just expanded the entire thing out, but i kinda did it out of laziness 05:45 MTDiscord but the sidebar search feature was really handy... for a book i dont think its truly neccesary 05:46 MTDiscord I should rephrase: I am fine with sidebars (there isnt much other way to do it), I just dont like how most markdown gets converted to it (styling? nav? idk) 05:46 MTDiscord For some reason I find Love docs to be really easy to navigate, even though they dont even have subsections https://love2d.org/wiki/love 05:46 MTDiscord I think that is entirely based on how you index your book. You could always just handwrite your own sidebar. 05:47 MTDiscord oh wow thats nice 05:47 MTDiscord Its a flippin mediawiki 05:47 MTDiscord Yet it might be my favorite doc page 05:48 MTDiscord I think we should spend more time talking about content and less about formats at this point, personally. Once we start writing content we can find out what may be missing from this or that approach. But I went to write content and realized the doc structure is different between Luanti/builtin and minetest_docs/docs, that threw me for a real loop. Though I understand the separation of concerns between engine devs and modders 05:48 MTDiscord My least favorite docs? MDN and Node. Awful docs them. Comprehensive but not comprehendable. 05:48 MTDiscord Enlightenment docs. Because I work on Enlightenment and we have no clue how to document things 05:48 MTDiscord FWIW this is a side conversation tbh 05:49 MTDiscord reminds me to work on my own book -_- 05:49 MTDiscord And wydm you just now realized? You just now realized the builtin lua_api.md is a monolithic file and minetest_docs is separate organization? ;p 05:49 MTDiscord i ended up getting distracted by another foss game 05:49 MTDiscord True, sorry, didn't mean to shut down the conversation 05:50 MTDiscord Put another way: what would be a good way for a new writer like me to contribute to the docs? I think I need to actually write a non-trivial mod first! 05:50 MTDiscord I think you just answered your own question 05:50 MTDiscord yeah me too 🙂 05:51 MTDiscord Make a food mod :juanchi_face: 05:51 MTDiscord make a mob api 05:51 MTDiscord A mob food api mod 05:51 MTDiscord Truely the worst of all worlds 05:51 MTDiscord But yeah, messing with the stuff is the best way (and probably the only way) to learn to make your own docs, and in fact my own book is (well, would be) essentially just me dumping rambling and pitfalls ive noticed. You have to take up all the gotchas and pitfalls to even document stuff first. 05:52 MTDiscord "I made a tool where you can eat part of a horse without killing it" - famous modder Dwight Schrute 05:52 MTDiscord That is terrifying, but I kinda wanna see it 05:52 MTDiscord Imagine a horse mob but you can take slices out of it 05:52 MTDiscord slowly becomes a stalhorse 05:52 MTDiscord Neko is your book a Luanti book or something else? 05:52 MTDiscord Luanti book and i quit writing it for some reason because i got busy 05:53 MTDiscord Isnt it generated from the main docs? 05:53 MTDiscord its full of terrible humor though and its a little different from the other books people write, i just wanted to make my own and have fun from it 05:53 MTDiscord no youre thinking of my doc generator thingy 05:53 MTDiscord https://swag.toys/minetest-docs/ 05:53 MTDiscord this one 05:54 MTDiscord yes thats not it 05:54 MTDiscord which one is that 05:54 MTDiscord I focused more on making a "humorous" book inspired by Beej's C/networking/IPC books which focus more on being funny enough to be engaging to read instead of dry and to-the-point https://gitgud.io/swagtoy/yamb-book 05:55 MTDiscord as far as I know, both https://swag.toys/minetest-docs/ and https://api.minetest.net/ are both generated from lua_api.md 05:55 MTDiscord click on book/ and Gitlab will generate a AsciiDoc render 05:55 MTDiscord >read it online >not found 05:56 MTDiscord https://gitgud.io/swagtoy/yamb-book/-/tree/master/book 05:56 MTDiscord So yamb is more like rubenwardys book than an api reference 05:56 MTDiscord Yessir 05:56 MTDiscord I also wanted to discuss engine internals too for those who wish to contribute 05:56 MTDiscord >A game is… a mod verifiably false 05:57 MTDiscord thats true yes 05:57 MTDiscord need to fix that 05:57 MTDiscord the biggest bulk of this was the Lua quick reference 05:57 MTDiscord but those are all collapsed i think 06:01 MTDiscord This reminds me that I definitely want to integrate an intro tutorial into the documentation 06:02 MTDiscord Something like the modding book, but a lot smaller, and more of a step-by-step hand hold 06:02 MTDiscord I think you should instead point to Ruben's book, really. 06:02 MTDiscord You can have examples, like those manpages do 06:02 MTDiscord We already point to it, but its not what I am looking for 06:02 MTDiscord All good projects need a great tutorial. I have liked Ruben's book so far 06:03 MTDiscord i think a tutorial for creating a mod might be nice, if that's what you mean 06:03 MTDiscord The API will have examples separately 06:03 MTDiscord That is what I mean. A "get started making something" guide 06:03 MTDiscord gotcha 06:04 MTDiscord The mod book is more of a handbook for everything Luanti has 06:04 MTDiscord Like an API reference but in prose 06:05 MTDiscord Instead of that, I want an interactive "Here's your very first project, here's a basic introduction to important concepts, congrats, you're making games" 06:05 MTDiscord Then it can continue onward to the api reference and the modding book 06:05 MTDiscord Again I think there are two types of docs, both relevant: references and guides. References explain how a given function works. Guides walk people through how to use a set of functions to accomplish a generic goal 06:06 MTDiscord I was using the Svelte guide the other day, and it made me realize that we really are missing something like that 06:06 MTDiscord References for advanced folks, guides for noobs like me. Both important, but different enough to be called out and separated. They can link to each other of course. 06:09 MTDiscord My only experience modding is Minecraft Bedrock (again I'm a Microsoft employee and Minecraft is owned by MSFT, I'm speaking unofficially and everything here is my own opinion) The open source community docs there were pretty good, and it felt clear the biggest thing lacking was clarity from Minecraft devs about what each function in the API did. That said, the provided TypeScript types were really well documented 06:11 MTDiscord https://bedrock.dev/ 06:12 MTDiscord Ick, separate nav pages 06:13 MTDiscord Cant get from Addons to Schemas without going home or searching :/ 06:13 MTDiscord The site isn't perfect, but I love searching so maybe I'm biased 06:14 MTDiscord Oh yeah, a good searchbar is good to have. ReadTheDocs search sucks (Blender docs used to be AWFUL) 06:14 MTDiscord I like discord.js search, and that bedrock search seems to work well too 06:15 MTDiscord Its just quicker to navigate a global nav, usually 06:16 MTDiscord Yes, both are super valuable 🙂 But neither work if there isn't good content at the core to be indexed 😉 06:17 MTDiscord Signing off for the night, have a good one everyone! Happy Game Jam!