You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
RST parser for console version of script documentation #963
Would it be possible to make a print-like command for Lua (or just its own script) that accepts markdown syntax? It doesn't need to be 100% faithful (maybe use colors for bold and italic), but something that could make sense out of the same markdown text used in the documentation on GitHub.
Context: documentation for scripts is now contained in the script files, between tokens that (in lua) denote a multiline comment or string (comment only in Ruby). This text is marked up in "restructured text" format, which is similar to markdown but better for large documents, and used to generate the html docs. It is also used as in-console help for some scripts - unifying the interactive help, documentation, and comments for maintainers. An upgrade to the dfhack core command "help" is planned which will make the docs for all scripts available without adding -help flags on a per-script basis.
Dirst - I think what you want is for help text in the console to have some actual formatting, rather than just dumping all the markup characters. This is a logical extension of the open issue, and actually pretty easy to do. (though IMO it's plenty readable anyway...)
There are, I think, only a few main constructs to handle.
bold, italics, and monospace can be handled by colors, and nesting is not supported.
The title is always the first word, on it's own line, and underlined with its length in ===== on the next line -- another color would do.
'Definition lists' have the term (command) first between colons, then spaces to align and the explanation (possibly multiline) -- just color term and remove the colons.
"::" indicates that the following (indented) block is monospaced; it should be replaced with ":" if on the end of a line or removed if nothing precedes it.
leading and trailing empty lines should be stripped.
cross-references are surrounded by single backticks -- another color.
It's not trivial, but nor would that be too difficult to implement in Lua.
changed the title [-]RST interpreter for console version of script documentation[/-][+]RST parser for console version of script documentation[/+]on Jul 15, 2016
Following #972 and associated docs changes, keybinding information should be printed after the in-script docs. It is appropriate that this be generated at runtime, instead of at build time as for the HTML docs.
Meaning something like help gui/settings-manager would include "bound to Alt-S@title"? That shouldn't be too hard, although the internal keybinding storage may be hard to search by command.
I suggest having one more layer of abstraction. I.e. first have something that parses the rst and the forms the console version. Then we could use the same parser to form df gui help (maybe even interactive and hyperlinked?)
@lethosor - exactly. The system I've implemented for the HTML looks like
Keybinding: Alt-S [-> "command with args"][ in context fort/whatever]
The "with args" and context sections are only included if the command bound has arguments and/or a context, respectively. I'd be surprised if the internal storage was set up to make this easy, but it's not impossible?
@warmist - How far do you want to go? ReStructuredText is designed to be readable 'in the raw', and it's pretty easy to do basic parsing as styles may not overlap (see above). A GUI could be pretty easy if we just use the same logic as the console but with clickable links. If you want to include non-script documentation in this system we'll need to use the raw text sources, which are included in the HTML docs.
Improved handling of plugin documentation in general would be really nice - docs are still always duplicated between docs/Plugins.rst and the console help, and thus often conflict or get out of date. Some system to have a single source of truth for these docs would be nice, especially if that allowed Travis to test their existence and certain formatting issues, and then pull the text into the html and plugin at build time.
Activity
[-]RST interpreter for console version of script documentation[/-][+]RST parser for console version of script documentation[/+]PeridexisErrant commentedon Aug 9, 2016
Following #972 and associated docs changes, keybinding information should be printed after the in-script docs. It is appropriate that this be generated at runtime, instead of at build time as for the HTML docs.
lethosor commentedon Aug 9, 2016
Meaning something like
help gui/settings-managerwould include "bound to Alt-S@title"? That shouldn't be too hard, although the internal keybinding storage may be hard to search by command.warmist commentedon Aug 10, 2016
I suggest having one more layer of abstraction. I.e. first have something that parses the rst and the forms the console version. Then we could use the same parser to form df gui help (maybe even interactive and hyperlinked?)
PeridexisErrant commentedon Aug 10, 2016
@lethosor - exactly. The system I've implemented for the HTML looks like
The "with args" and context sections are only included if the command bound has arguments and/or a context, respectively. I'd be surprised if the internal storage was set up to make this easy, but it's not impossible?
@warmist - How far do you want to go? ReStructuredText is designed to be readable 'in the raw', and it's pretty easy to do basic parsing as styles may not overlap (see above). A GUI could be pretty easy if we just use the same logic as the console but with clickable links. If you want to include non-script documentation in this system we'll need to use the raw text sources, which are included in the HTML docs.
Improved handling of plugin documentation in general would be really nice - docs are still always duplicated between
docs/Plugins.rstand the console help, and thus often conflict or get out of date. Some system to have a single source of truth for these docs would be nice, especially if that allowed Travis to test their existence and certain formatting issues, and then pull the text into the html and plugin at build time.Update manager-quantity docs and fix with Lua 5.3