| Time |
Nick |
Message |
| 00:21 |
mrcheese |
xD |
| 00:23 |
user333_ |
i found another typo... opening a PR soon |
| 00:24 |
mrcheese |
alr now lets see how fast a PR can get merged |
| 00:24 |
* mrcheese |
wants to guess like 30 seconds :PPP |
| 00:29 |
MTDiscord |
<wsor4035> sees no prs |
| 00:29 |
user333_ |
hold on a min |
| 00:30 |
user333_ |
3 |
| 00:30 |
user333_ |
2 |
| 00:30 |
user333_ |
1 |
| 00:30 |
user333_ |
opened |
| 00:32 |
user333_ |
tada! |
| 01:11 |
MTDiscord |
<mark.wiemer> One for high-level tracking of making the docs parse able, one for lower level discussion of the specific Markdown schema, if we go that route. There's already pushback from appgurueu about Markdown schema, so I think the separation of discussions has proven useful |
| 01:13 |
MTDiscord |
<mark.wiemer> OK, is the suggestion then to rewrite everything we have in a LOVR-like lang? The biggest value of Markdown is the fact that most of our (and the world's) docs are already Markdown. I'd rather start by cleaning up what we have. Then we can automatically transform it into any future format |
| 01:18 |
|
MTDiscord joined #luanti-docs |
| 01:26 |
MTDiscord |
<mark.wiemer> Markdown is a consistent machine parse able schema though 🙁 |
| 02:08 |
MTDiscord |
<greenxenith> Markdown is not a schema |
| 02:18 |
MTDiscord |
<greenxenith> Mark is willing to do the work to make a strict markdown schema, so feel free to challenge it with a Lua DSL |
| 02:19 |
MTDiscord |
<greenxenith> Stop bikeshedding, just do it |
| 02:23 |
MTDiscord |
<greenxenith> inb4 "but its more fundamental than the shed paint color" We operate on results here. Hypotheticals and perfect design do more harm than good at this level. The engine may be a behemoth with too much inertia to fundamentally change at this point, but these projects are much smaller and we get more value by just trying things. Just like we tried AsciiDoc and it didnt go well, and we tried Hugo and it went fine |
| 02:25 |
MTDiscord |
<exe_virus> Oh we're markdown now? neat |
| 02:26 |
MTDiscord |
<greenxenith> ... lua_api has been md for 7 versions now |
| 02:32 |
MTDiscord |
<exe_virus> I thought we were talking about the docs site |
| 02:32 |
MTDiscord |
<greenxenith> And technically its been markdown since day one, just not labeled as .md |
| 02:32 |
MTDiscord |
<exe_virus> I'm aware Lua API is md |
| 02:32 |
MTDiscord |
<exe_virus> My b |
| 02:32 |
MTDiscord |
<greenxenith> Ah, right. The original docs project is still ADoc, but the docs site is a markdown conversion from the wikis |
| 02:33 |
MTDiscord |
<greenxenith> Er, the original project is the ADoc content converted to markdown as well |
| 02:35 |
MTDiscord |
<greenxenith> And this conversation is particularly about the lua_api conversion which is what the original project was for |
| 02:36 |
MTDiscord |
<exe_virus> Oh, I'm very out of the loop, ignore me |
| 02:41 |
MTDiscord |
<mark.wiemer> Markdown turns into HTML, if it's not machine readable I'm not sure what is. There are talks of other machine readable approaches like a Lua DSL but we'd have to make sure it's still easy to write docs. Markdown is extremely lightweight and flexible. Yaml and JSON not so much. A DSL, well, it'd depend, but the snippet shown so far look like JSON and not very promising. I think long term will still be handwritten docs honestly, |
| 02:41 |
MTDiscord |
ultimately doc-writint is a very human process, not reasonable to fully automate |
| 02:42 |
MTDiscord |
<greenxenith> When we say "machine readable" we mean "can a machine divide this into meaningful tree" |
| 02:42 |
MTDiscord |
<greenxenith> Not "can a program read the bytes" |
| 02:42 |
MTDiscord |
<mark.wiemer> Yes, that's literally how it turns into HTML. What am I missing here? |
| 02:42 |
MTDiscord |
<greenxenith> No, it turns markdown elements in to HTML elements |
| 02:43 |
MTDiscord |
<mark.wiemer> Yes? That's a machine that does that, is it not?m |
| 02:43 |
MTDiscord |
<greenxenith> See this, please |
| 02:43 |
MTDiscord |
<greenxenith> A meaningful tree |
| 02:43 |
MTDiscord |
<greenxenith> As in, relate one section to another based on a consistent set of rules |
| 02:43 |
MTDiscord |
<greenxenith> Have you seen the luanti-tools script that breaks the lua_api.md into API snippets? Its awful |
| 02:44 |
MTDiscord |
<greenxenith> And you have already proposed a solution for that, being a strict schema to keep the markdown organized |
| 02:44 |
MTDiscord |
<greenxenith> Why are we still bikeshedding |
| 02:44 |
MTDiscord |
<mark.wiemer> ??? markdown is a meaningful tree. That's why we get HTML lists and not just plaintext pages. I am very confused. |
| 02:44 |
MTDiscord |
<mark.wiemer> Markdown turns into a meaningful tree* |
| 02:44 |
MTDiscord |
<mark.wiemer> Already replied to that with my own comment :/ |
| 02:45 |
MTDiscord |
<mark.wiemer> This is my reply |
| 02:45 |
MTDiscord |
<greenxenith> I cant tell you what you are missing then |
| 02:45 |
MTDiscord |
<mark.wiemer> Why do you say Markdown isn't machine readable? |
| 02:45 |
MTDiscord |
<greenxenith> It is as machine readable as a text file |
| 02:45 |
MTDiscord |
<greenxenith> We are not using "machine readable" in a literal sense, as I tried to make clear already |
| 02:46 |
MTDiscord |
<mark.wiemer> It is more readable. It defines ### as "third level heading", which a text file does not. |
| 02:46 |
MTDiscord |
<mark.wiemer> There is such a thing as syntactically invalid Markdown. It's much harder to generate syntactically invalid text. |
| 02:47 |
MTDiscord |
<mark.wiemer> What does machine readable mean? |
| 02:47 |
MTDiscord |
<greenxenith> Fine: Markdown is not [the concept which applies to the lua_api.md in its current state where it is near-impossible to write an automated application which converts the markdown (or whatever text is written) into a format which something like a language server or documentation lookup could use] |
| 02:47 |
MTDiscord |
<greenxenith> Machine parseable, machine readable, destructable, modular, pick whatever word you want |
| 02:47 |
MTDiscord |
<mark.wiemer> No, raw Markdown is not LSP-parseable. I agree there. |
| 02:48 |
MTDiscord |
<mark.wiemer> You are asking for compliance with a specific protocol, let's just name that protocol. It's LSP. |
| 02:48 |
MTDiscord |
<greenxenith> I am not asking for LSP compliance, I am asking for any consistent organization whatsoever to make it consistently parseable |
| 02:48 |
MTDiscord |
<mark.wiemer> Consistently parse able into what?? |
| 02:49 |
MTDiscord |
<wsor4035> think javadoc, etc schema so a machine can parse it to whatever |
| 02:49 |
MTDiscord |
<greenxenith> An LSP is one possibility |
| 02:49 |
MTDiscord |
<greenxenith> Please help me understand what I am failing to convey |
| 02:50 |
MTDiscord |
<mark.wiemer> That is what I am trying with my questions, yes |
| 02:50 |
MTDiscord |
<mark.wiemer> I think we are agreed we need something that exposes the types of the args to a machine, as that's not currently present. |
| 02:50 |
MTDiscord |
<greenxenith> That is a very large step to making it [insert the term we apparently cannot agree on] |
| 02:51 |
MTDiscord |
<mark.wiemer> "it" is vague here. If you mean "Make the API parse able" like I defined in #296, yeah |
| 02:52 |
MTDiscord |
<greenxenith> How-- what? How is it vague at all, we have exclusively been talking about the API? |
| 02:52 |
MTDiscord |
<mark.wiemer> Another issue is that "lua_api.md" covers much more than the raw API |
| 02:53 |
MTDiscord |
<mark.wiemer> Only the core namespace reference is really the API, you have mentioned the file itself so I've been confused. I'm also dumb. Never underestimate how dumb I am! |
| 02:53 |
MTDiscord |
<mark.wiemer> https://github.com/luanti-org/docs.luanti.org/issues/296 for reference |
| 02:54 |
MTDiscord |
<greenxenith> If we are talking about "markdown" and say "API" in the same sentence I believe it reasonable to assume we are referring to lua_api.md |
| 02:56 |
MTDiscord |
<greenxenith> When you say "reference" I see "API reference" which is lua_api.md |
| 02:58 |
MTDiscord |
<greenxenith> Evidently Luatic does not agree that a markdown schema is as good as a DSL when it comes to parseability, but I say you both start writing documentation in your chosen approach and compare. |
| 03:03 |
MTDiscord |
<mark.wiemer> Api référence is a small part of lua_api.md |
| 03:03 |
MTDiscord |
<greenxenith> Balancing catering to the writer vs catering to the developer is difficult, but I generally agree that writing is more important to some extent. It may be valuable to validate against the actual engine API in some way, but that should be a secondary concern |
| 03:04 |
MTDiscord |
<greenxenith> Unfortunately lua_api.md does not care what you think |
| 03:04 |
MTDiscord |
<greenxenith> https://cdn.discordapp.com/attachments/926231483155378176/1443075025618866307/image.png?ex=6927bfd9&is=69266e59&hm=0164da4b9e94328d4906fc6cc890a2b78c9c193e16e8e0f4fe51b54f6b322715& |
| 03:05 |
MTDiscord |
<mark.wiemer> Also, sorry I have been rude. I have not eaten in a while, and I have been impatient. That is my fault, and I'll try to think more before I speak |
| 03:05 |
MTDiscord |
<mark.wiemer> Just because they named it that, doesn't make it correct. Most of the doc is guidelines, I am focused on the part that actually defines functions. The actual API. |
| 03:06 |
MTDiscord |
<greenxenith> My point is we call it by what it is labeled. If we see "api reference" we think of the document labeled "api reference" whether or not it is in its entirety an API reference. I would also argue that most of it defines functions. |
| 03:07 |
MTDiscord |
<greenxenith> No worries. I should also try to be more patient. And less defensive. |
| 03:08 |
MTDiscord |
<mark.wiemer> OK, I will use "core namespace reference" from now on. That is where I am focusing |
| 03:08 |
MTDiscord |
<greenxenith> While some of the reference includes non-function items (like engine behavior, file structure, etc), most of it is function definitions. I am not sure what else makes it not an API reference |
| 03:09 |
MTDiscord |
<mark.wiemer> The core namespace reference should include types of args and return types of functions in a consistent way that machines can extract and convert to other formats, e.g. for a language server |
| 03:09 |
MTDiscord |
<mark.wiemer> I will reread the doc. But my focus has been on core namespace reference. Maybe we align on changes there, then broaden our scope? |
| 03:10 |
MTDiscord |
<greenxenith> The problem is the whole doc is "core namespace reference" |
| 03:10 |
MTDiscord |
<greenxenith> I am not sure what else you are referring to |
| 03:10 |
MTDiscord |
<greenxenith> When we say "lua_api.md" we also mean core namespace reference |
| 03:10 |
MTDiscord |
<mark.wiemer> There is a specific section named "core namespace reference" |
| 03:10 |
MTDiscord |
<greenxenith> Source? |
| 03:10 |
MTDiscord |
<mark.wiemer> https://api.luanti.org/core-namespace-reference/ |
| 03:11 |
MTDiscord |
<greenxenith> OK yikes |
| 03:12 |
MTDiscord |
<greenxenith> Severly dislike the 'quotes' around that |
| 03:12 |
MTDiscord |
<mark.wiemer> It happens 🙂 |
| 03:12 |
MTDiscord |
<greenxenith> You are aware that the Luanti API includes more than the core namespace, yes? |
| 03:12 |
MTDiscord |
<mark.wiemer> I have an idea what you mean, but I'll ask you to clarify to be sure. |
| 03:13 |
MTDiscord |
<greenxenith> There are other detached objects that arent under the core table, and parameters that are simply Lua tables that are defined outside of that sectoin |
| 03:14 |
MTDiscord |
<greenxenith> Almost everything in lua_api.md is critical to the API reference even if it isnt in that specific section |
| 03:14 |
MTDiscord |
<greenxenith> For example, above that section is https://github.com/luanti-org/luanti/blob/master/doc/lua_api.md#registered-entities which defines the methods that the entity object has |
| 03:15 |
MTDiscord |
<greenxenith> I believe my confusion is arising from the notion that lua_api.md somehow isnt primarily documenting methods and functions, which it absolutely is |
| 03:17 |
MTDiscord |
<mark.wiemer> I think you're right. I was confusing it with some other doc or just being dumb, sorry |
| 03:17 |
MTDiscord |
<mark.wiemer> I think the best area to start with is the core namespace reference still, it's closest to something LSP-compatible, I believe |
| 03:18 |
MTDiscord |
<greenxenith> Whatever order gets you there faster |
| 03:18 |
MTDiscord |
<exe_virus> It specifies: - methods/functions - data structures/member variables/their specification therin - expected file structures and contents of those files |
| 03:19 |
MTDiscord |
<greenxenith> If you actually write a couple paragraphs of documentation in your system, it will already be objectively better than Luatic's approach since he hasnt done anything with it yet |
| 03:19 |
MTDiscord |
<exe_virus> I'm curious - mark you are planning to use a schema or a DSL? |
| 03:20 |
MTDiscord |
<greenxenith> As per the conversation from yesterday: He is writing a remark.js schema to strictly format markdown |
| 03:21 |
MTDiscord |
<exe_virus> Ah, sounds good as a solution, the fun part will be building our meta tree schema - looking forward to the buckets we build |
| 03:23 |
MTDiscord |
<mark.wiemer> Very rough v1 already done, ref the GH issue and my comments |
| 03:23 |
MTDiscord |
<mark.wiemer> Buckets? |
| 03:25 |
MTDiscord |
<exe_virus> structures is a "bucket", such as all our "definitions" table. methods core. methods these fall into the "methods" bucket, and can be further specified under the "core" and "table" method buckets |
| 03:26 |
MTDiscord |
<exe_virus> i.e. how we group common items, and how those common items will be specified such that one "method" is the same as another "method" from a computer language trying to parse it, standpoint |
| 03:26 |
MTDiscord |
<mark.wiemer> Hmm, would be interested in reading any docs about that process and naming convention, it's new to me 🙂 in any case, yeah, I'll be writing sample schema-compliant docs over the week |
| 03:26 |
MTDiscord |
<exe_virus> cool, yeah I do it for work a lot, will take a look when you have it |
| 03:28 |
MTDiscord |
<mark.wiemer> Signing off for now, need a snack and some sleep. Thanks for the patience and the convo today 🙂 |
| 05:00 |
|
MTDiscord joined #luanti-docs |
| 08:33 |
|
mrcheese joined #luanti-docs |
| 13:39 |
MTDiscord |
<luatic> There isn't really (unless you consider text encoding issues), if it's invalid it just defaults to rendering the invalid parts as text. It does not happen that you enter [foo](bar into some Markdown box and are presented with "syntax error: forgot to delimit link target" or something. |
| 13:45 |
MTDiscord |
<luatic> Exactly, and this kind of thing is what Markdown doesn't provide a good structured representation for. Markdown lets you write down a tree, but this tree is ultimately a HTML DOM, so it's all about how things should look like, and not that much about semantic information. It's not XML, it's not really supposed to be extensible. Now you technically can do custom HTML tags, you can do <div class="blah"> etc., but I find that to be fairly |
| 13:45 |
MTDiscord |
verbose. How would you write down types in LaTeX, for example? <type-list><type-int></type-list> would be too verbose, so won't you just end up using text and doing the tree-ification yourself? |
| 13:46 |
MTDiscord |
<luatic> Anyways, I agree with Green: We'll just have to try it. At the end of the day I'm mostly yapping so far, maybe my idea turns out horribly unconvenient in practice. No other way to find out than for me to go give it a shot 🙂 |
| 17:16 |
|
Niklp4 joined #luanti-docs |
| 17:22 |
|
MTDiscord joined #luanti-docs |
| 21:11 |
|
mrcheese joined #luanti-docs |
| 23:19 |
MTDiscord |
<mark.wiemer> This is specific to Minetest Game, right? |
| 23:19 |
MTDiscord |
<mark.wiemer> https://cdn.discordapp.com/attachments/926231483155378176/1443380729944871002/Screenshot_2025-11-26-17-19-07-57_df198e732186825c8df26e3c5a10d7cd.jpg?ex=6928dc8e&is=69278b0e&hm=14ae23d8ab13d568894f5d59665940fe5c8d6f8204620745544b0a29f2da8a83& |
| 23:21 |
MTDiscord |
<wsor4035> and the soups, yes |
| 23:35 |
|
rubenwardy joined #luanti-docs |
| 23:39 |
MTDiscord |
<mark.wiemer> Cool just triple checking |
