Time Nick Message 22:35 MTDiscord https://github.com/luanti-org/docs.luanti.org/issues/296#issuecomment-3736141692, 🙂 TLDR: I still want Markdown, not MDX, because we can easily add MDX later. We need to write our own schema, checker, transformer, LSP server, and VS Code extension to get this work done. I've detailed a bit better what I mean with each of those terms in a new glossary section. 23:14 MTDiscord I think the true body of work is best described by new issue https://github.com/luanti-org/docs.luanti.org/issues/312, titled "Integrate Lua API information into IDEs", but I do want to keep the conversations focused on relevant sub-issues where valuable 23:16 MTDiscord Curious what you all feel would be necessary to close new issue https://github.com/luanti-org/docs.luanti.org/issues/315, titled "Agree on an approach for making docs parsable" 23:31 MTDiscord We dont need 2 issues for this 23:32 MTDiscord 315 is 100% a duplicate of 296 23:34 MTDiscord This is also bikeshedding. We already agreed on markdown and a schema, and I have yet to see a practical clean implementation of such a schema 23:35 MTDiscord ok, so i looked at this link briefly, no schema, seems worthless 23:36 MTDiscord guess i should actually read it 23:36 MTDiscord ok yeah, no schema proposed in it 23:36 MTDiscord I like how its taken this much discussion to reach a conclusion we had already come to months ago. 23:37 MTDiscord also i dropped mdx forever ago in favor of using html in the markdown for the schema 23:37 MTDiscord mostly for compatibility and integration reasons 23:37 MTDiscord Yes, we want to use markdown or similar. Yes, we need to rewrite the whole docs. Yes, we need a parser/validator for the markdown. Yes, we need to be able to output to something an LSP can use. None of this is new. 23:37 MTDiscord also note my suggestion is more of a concept of a plan than a plan. 23:38 MTDiscord "markdown or similar" is not specific, is there anything blocking us from agreeing on "Markdown", period, no qualifier? 23:39 MTDiscord we already agreed on that ages ago 23:39 MTDiscord "markdown or similar" meaning I dont care 23:39 MTDiscord not new, but not written down 23:39 MTDiscord OK, I think I'll close https://github.com/luanti-org/docs.luanti.org/issues/315 saying we agree on using Markdown? 23:39 MTDiscord Yes, do it 23:40 MTDiscord having two issues for this seems pointless 23:40 MTDiscord https://cdn.discordapp.com/attachments/926231483155378176/1460055700746145926/image.png?ex=69658655&is=696434d5&hm=5e39db3e9d3a1a3ea67a30debf8bd9ffb9671985a08eeea14c86c7a407365af2& 23:40 MTDiscord did you read the descriptions? 23:40 MTDiscord but idrc 23:40 MTDiscord yes 23:41 MTDiscord ok, i expand it to all of these. given we should only care about ides that support lsp, but 🤷 23:41 MTDiscord https://cdn.discordapp.com/attachments/926231483155378176/1460055989444415576/image.png?ex=6965869a&is=6964351a&hm=57b212484648a902b1196960ec13ec60efa6fbe7a52ca8250616a4f08c200e87& 23:41 MTDiscord OK. I'll quickly comment that I feel like I"m getting a lot of flak for a good faith effort that does document things that weren't previously documented in GitHub 🙁 23:41 MTDiscord Im only giving you flak for the duplicate, I think the others are fine 23:41 MTDiscord I'm not sure what you mean. You expand your belief that it seems pointless? I just don't think that's constructive 23:42 MTDiscord this comes off as "flak" to me for the record. Just doesn't seem constructive, if anything, it's discouraging 🙁 23:42 MTDiscord Alright, fair 23:42 MTDiscord I am heavily against bikeshedding, and this feels like bikeshedding to me, which is also not constructive 23:42 MTDiscord vscode extension is going to be 99% the same as any other ide as lsp is a thing. its just packaging and submitting, not sure that the two issues are justified, but idrc 23:43 MTDiscord From our point of view, you were already working on a markdown schema solution, and now we are going back to this for some reason. 23:43 MTDiscord I strongly disagree that this is bikeshedding. Up until 2 weeks ago I was strongly considering LuaCATS or TypeScript, would've been a radically different path 23:43 MTDiscord lets move on from having a bunch of issues unless someone else cares. 23:43 MTDiscord I tried to clarify with the title of "make docs programmatically parsable" that the goal was not approach-specific, e.g. it could've been LuaCATS, Markdown, other. 23:44 MTDiscord I want to have many small issues to clearly break down what is effectively a huge body of work 23:44 MTDiscord At some point breaking down issues too far just makes needlessly little issues. There is a saying for this I dont remember. 23:44 MTDiscord personally i think its boreding on over management, but as you are a team member, i trust you and defer to your "expertise" because i dont care enough 23:44 MTDiscord But I dont mind breaking the problem down, I see value in the other issues 23:45 MTDiscord I did say I'd be working on a checker/transformer POC but I ended last convo with "why not use MDX, I don't care, just saying" but that convo lasted a long time so I felt it worth documenting 23:45 MTDiscord I believe I am also put off because I didn't see any other team members heavily backing things outside of markdown 23:46 MTDiscord anyways, if i understand the current pile of issues, we should be focusing on https://github.com/luanti-org/docs.luanti.org/issues/297 now and getting people to solicit proposals for what such a schema should look like? 23:46 MTDiscord and then I created the GH issues to give myself a good feel for the different pieces of work we need. I don't think it'll be a trivial bit of work to turn LSP data into VS Code extension. As someone who wrote hello world in LSP VS Code extension and maintains another LSP VS Code extension, there is a lot nuance. It's not a few clicks or lines of code by any means 23:46 MTDiscord The VSCode extension is not our concern right now, at least 23:46 MTDiscord yes, next step is to get what a proposal should look like. we already have the riseup pad, a gist, and other docs to reference. I'll be going through those in detail next and making my own proposal 23:47 MTDiscord correct, but it is on the backlog as it is something I want us to take up eventually. Hence the issue creation 23:47 MTDiscord Which I am fine with 23:47 MTDiscord OK, I'm off to a thing, see you guys in several hours or tomorrow or next weekend 😄 23:47 MTDiscord can you only pin two issues on github? 23:47 MTDiscord 3 I think 23:47 MTDiscord I swear ive seen 3 23:47 MTDiscord same 23:47 MTDiscord trying to figure out pinning an issue 23:47 MTDiscord having a dumb moment 23:48 MTDiscord found it 23:48 MTDiscord pinned #297 as its the current focus/priority 23:48 MTDiscord @ExeVirus would you be so kind as to comment your proposed markdown schema in https://github.com/luanti-org/docs.luanti.org/issues/297 23:52 MTDiscord i will comment mine too 23:53 MTDiscord For schemas: * We should identify what type if information is critical for using the API, what information is useful, and what is optional * The format does not have to be perfected since a consistent schema will allow us to change it at any time fairly trivially * Examples, examples, examples 23:55 MTDiscord done, i prefer the markdown-custom style less after trying out the XML style. 23:55 MTDiscord i hide a bunch of the existing stuff, since it was all rather offtopic 23:56 MTDiscord but ofc, i'm not part of the docs team so the choices are up to you guys 23:56 MTDiscord would you mind putting a quick code sample in your comment? 23:56 MTDiscord ok 23:57 MTDiscord I have to imagine some sort of YAML-like would be much more concise while retaining the XML type of sctructure 23:59 MTDiscord i argued in the riseup docs the same thing. my comments are still visible if you see the raw text 23:59 MTDiscord sorry, not the same thing, rather that it could be YAML or any similar language