Skip to content

RST parser for console version of script documentation #963

Open

Description

@PeridexisErrant

When dumping script documentation to the console (#947), it would be nice to interpret the markup.

bay12 discussion here

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.

Activity

  1. changed the title [-]RST interpreter for console version of script documentation[/-] [+]RST parser for console version of script documentation[/+] on Jul 15, 2016
  2. PeridexisErrant commented on Aug 9, 2016

    @PeridexisErrant
    ContributorAuthor

    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.

  3. lethosor commented on Aug 9, 2016

    @lethosor
    Member

    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.

  4. warmist commented on Aug 10, 2016

    @warmist
    Member

    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?)

  5. PeridexisErrant commented on Aug 10, 2016

    @PeridexisErrant
    ContributorAuthor

    @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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions