In game documentation tool

[S-S-X]

Tool that can hold and display node documentation, maybe also docs for mobs.

Documentation management, how it should be done? Static files containing docs probably wont work very well and easily get outdated. Allow editing documentation in game with some privileges or voting?

• Voting system can get complicated especially if there's not many user for said tool / nodes but not sure.
• Privilege system disallows contributions but protects man pages so nobody can fill those with trash.

If in game editing of docs then would be good to still provide initial database and also have database in format that can be merged easily, that way database provided with tool could be updated in repository easily without special tools.

---

For MVP:

• [ ] Static content files for few nodes, no in game editors, single file / node.
• [ ] Indexing of said files during server startup.
• [ ] Tool that can read those files and display contents based on targeted node name.
• [ ] Register nodes for tool based on files indexed during server startup.

Above makes content files to be definition of registered / supported nodes for documentation tool, simply adding new content file should enable said node for tool without touching lua code at all.

[6r1d]

Documentation management, how it should be done? Static files containing docs probably wont work very well and easily get outdated.

I'm not sure static / lua files are that bad; we all use tools and it's easier to copy-paste some API calls for LuaC. Especially for people who are starting with digilines mod.

Allow editing documentation in game with some privileges or voting?

Is it easy enough to implement considering those formspecs might be interactive? I can easily imagine a menu like "api calls", "recipes", "advices".

GitHub + Lua files should be enough: we can simply edit text here, the problem with documentation is thinking in terms "things I need immediately while interacting with a block" and "what someone else needs".

[S-S-X]

I'm not sure static / lua files are that bad

I do agree that static files are not that bad but lua files for large amounts of content imo is very bad because you have to watch for syntax and do escaping, things that should not be needed for content.

we all use tools and it's easier to copy-paste some API calls for LuaC

Might be that I did not fully understand this one, but if I did then I cannot see how is it easier to copy stuff from .lua file than .yaml or .md or .txt file that is formatted to be mergeable with diff tools? However I can see how it is bit harder with .lua files if you have to escape/unescape to copy/paste things from file containing documentation content.

Is it easy enough to implement considering those formspecs might be interactive?

Yes. Even if content would be completely static I would still go with separate files containing actual content. Adding more documentation should not require changing or adding single line of code.

Editing that content in game of course requires bit more than only reading content from files: integrated text editors possibly with simple markdown like parsers (or very restricted content like only sections with headers and text for each section). Then another required thing is serializer that has required features (markdown possibly) with safe way (only almost safe ways currently available afaik) to write modified contents back to database (which is probably flat file).

GitHub + Lua files should be enough: we can simply edit text here, the problem with documentation is thinking in terms "things I need immediately while interacting with a block" and "what someone else needs".

Agreed with "Github" part here but not really with "Lua files" part because of reasons stated above. However "we can simply edit text here" still holds no matter what is file format.

After thinking through these I think best way to proceed forward would be to define flat file database format that can be migrated easily to different format if needed. Possible formats that comes to mind would be:

• Markdown, MIT licensed parser for lua https://github.com/mpeterv/markdown.
• YAML. This requires indentation for every line. Both parsing and serialization is extremely complex.
• Custom key/value style content storage, restricts to series of heading + content for documentation pages.
• Text files as is, everything displayed as written in files. Single file can only contain single topic.

[S-S-X]

And should not try to include in game documentation editors but keep that possibility open and consider that it might be added some day.

[6r1d]

Sure, I'd prefer either Markdown or a simplified version of it. Even if current library doesn't solve our requests, we can replace / rewrite it down the line. We can also use "titles" functionality and hide each text section behind some button, unless there's only one section for everything.

YAML will not be as fun for docs, really.

Custom key/value style content storage, restricts to series of heading + content for documentation pages.

Simplified Markdown might work, we probably can't use all Markdown's formatting capabilities in formspecs.