| Time |
Nick |
Message |
| 04:00 |
|
MTDiscord joined #minetest-docs |
| 04:39 |
MTDiscord |
<greenxenith> Guys why the hell did we not go with Pandoc? @Luars and @Josiah (Sie/Sie) both highlighted some great advantages and @Lua 'n Coffee was familiar with it. |
| 04:39 |
MTDiscord |
<greenxenith> We can use it as a markdown template engine and convert to other formats for publishing |
| 04:40 |
MTDiscord |
<greenxenith> With a familiar syntax (markdown) |
| 04:42 |
MTDiscord |
<greenxenith> I guess it was just the unfamiliar syntax that really killed it once we started. We should have tried writing in it before committing. |
| 04:43 |
MTDiscord |
<greenxenith> The tooling for Asciidoc was fine and it had use, but we didnt realize the syntax was gonna be an obstacle |
| 04:44 |
MTDiscord |
<greenxenith> With Pandoc markdown we can leverage the existing documentation (🎉) and use fancy features (templating/macros, metadata, format conversion) |
| 05:02 |
MTDiscord |
<greenxenith> It also supports Lua for custom filters |
| 05:06 |
MTDiscord |
<benrob0329> I haven't used Pandoc much, and honestly have never gotten it's macros to work right |
| 05:07 |
MTDiscord |
<greenxenith> It only supports LaTeX macros natively, so that would need to be done in Lua, which is rather simple |
| 05:14 |
MTDiscord |
<benrob0329> I mean, it's filter API looks fine, I'd have to dig into how to add custom elements though to really know how painful it'd be to add macros |
| 05:14 |
MTDiscord |
<greenxenith> Better than Asciidoc, IMO |
| 05:15 |
MTDiscord |
<benrob0329> Well sure, Ruby is not my strong suit and requiring the whole ruby distrobution to do so makes Adoc's plugins super painful |
| 05:15 |
MTDiscord |
<benrob0329> (which is why I've abandoned Asciidoc for my own projects) |
| 05:15 |
MTDiscord |
<greenxenith> Being able to use markdown is also very helpful |
| 06:07 |
MTDiscord |
<greenxenith> Simple macros are really easy ... will take some research to figure out renderable macros (inserting markdown) |
| 06:09 |
MTDiscord |
<benrob0329> It looked like you could insert text in the original format, it'll let you filter based on the input format |
| 06:10 |
MTDiscord |
<benrob0329> kinda like this: https://pandoc.org/lua-filters.html#center-images-in-latex-and-html-output |
| 06:10 |
MTDiscord |
<benrob0329> Not sure how to do it with Markdown specifically though |
| 12:19 |
rubenwardy |
I've used restructured text (.rst) before for docs, asciidoc is very nice in comparison |
| 14:21 |
|
ShadowNinja joined #minetest-docs |
| 19:19 |
MTDiscord |
<greenxenith> Yeah I looked at rst because it looked like it had the goals I wanted, but the syntax seemed rather different |
| 19:20 |
MTDiscord |
<greenxenith> Asciidoc would be nicer than that indeed, since the syntax is at least somewhat similar to md |
| 19:21 |
MTDiscord |
<luatic> I love me some pandoc. I personally have a custom filter to use AsciiMath instead of LaTeX, though for the little math we got, LaTeX as is standard would be fine too. |
| 19:22 |
MTDiscord |
<luatic> The way AsciiDoc does admonitions is nice, but that's probably about the only thing. |
| 19:23 |
MTDiscord |
<greenxenith> As much as ADoc had some niceties, I dont think they outweigh its obstacles |
| 19:24 |
MTDiscord |
<luatic> I agree |
| 19:25 |
MTDiscord |
<luatic> Supposedly we can go ADoc -> docbook -> markdown if we want to switch btw, not sure how well that'll work though. |
| 19:25 |
MTDiscord |
<greenxenith> Pandoc supports ADoc as an input language, so I dont see why it couldnt just convert straight to markdown |
| 19:26 |
MTDiscord |
<luatic> oh I wasn't aware of that (and apparently neither was the internet :P) |
| 19:26 |
MTDiscord |
<luatic> Markdown should give us much better integration overall, for example it should be much easier to set up SSG e.g. via Jekyll vs the horrors of the single ADoc SSG there is |
| 19:27 |
MTDiscord |
<greenxenith> Wait no, let me double check. It could be an output lang. |
| 19:27 |
MTDiscord |
<luatic> Yeah that's what I'm seeing |
| 19:27 |
MTDiscord |
<luatic> "→ = conversion to", "→ AsciiDoc" |
| 19:27 |
MTDiscord |
<luatic> on https://pandoc.org/ |
| 19:28 |
MTDiscord |
<greenxenith> https://github.com/gmarpons/asciidoc-hs |
| 19:34 |
MTDiscord |
<greenxenith> Either way, its not too difficult to migrate what we've got |
| 19:35 |
MTDiscord |
<greenxenith> First thing is we need a proper macro filter (that can insert rendered markdown) and system for defining methods/objects |
| 23:19 |
erle |
what do you mean with markdown when you talk about it? github-flavored markdown? |
| 23:32 |
MTDiscord |
<greenxenith> Doesnt really matter |
| 23:32 |
MTDiscord |
<greenxenith> Pandoc supports a handful of them |
| 23:32 |
MTDiscord |
<luatic> Personally I'd go with GFM |
| 23:38 |
erle |
luatic rationale? |
| 23:40 |
MTDiscord |
<wsor4035> heh, seems the ban was extended here |
| 23:40 |
MTDiscord |
<wsor4035> same |
| 23:40 |
erle |
? |
| 23:41 |
erle |
wsor4305 am i supposed to be banned in this channel and someone forgot? |
| 23:42 |
MTDiscord |
<wsor4035> roller already converted it once, and the result isnt bad |
