Dev Docs: Reformat RPC/REST Tables To 2 Lines Per Entry

[harding]

This replaces Markdown-created tables with lists that are converted into tables by CSS. A key feature is that each entry now occupies two lines of the table, giving each field more space for improvement (or allowing us to add extra fields later on). Here's an example:

@jonasschnelli you may want to review regarding your issue #723

@darioteixeira you may want to review regarding the ongoing discussion in pull #753

This uses CSS flexbox, which is apparently supported by all recent browsers, and most browsers that people use: http://caniuse.com/#search=flexbox

I tested it works on:

• Iceweasel (Firefox) 31.4
• IE11
• Chromium 40.0

It did not work for me on:

• Ancient Android 2.3.5 built-in browser

Looking at the table linked above, in my opinion, I think it's reasonable to expect developers to use one of the supported browsers.

For Reference

Here's the sed script that converted all of the files. (I did have to manually change parts of _includes/helpers/vars.md and change one character in the REST get_block.md file. Everything else was automatic.)

## On lines that start with a pipe:
/^|/ {
    ## Delete all table header/table body divider lines
    /|----/d;

    ## Replace lines that look like NTPD headers with a Liquid variable
    s/^| Name *| Type.*/{{json_table}}/;

    ## Delete extraneous whitespace
    s/ *|/|/g;

    ## Replace the first pipe with an asterisk to start a new list item
    s/^|/*/;

    ## Replace the remaining pipes with a new line and asterisk to start new list items
    s/|/\n*/g;

    ## Delete extraneous <br> in presence column
    s/\* Required<br>/* Required /;
    s/\* Optional<br>/* Optional /;

    ## Add an empty line after the last list item built from a single
    ## table row.  This improves readability/maintainability
    s/$/\n/;
}

## Delete the old table class and the trailing empty line
/{:.ntpd}/ {
    N;
    d;
}

[harding]

Forgot to add: full HTML preview here: http://dg1.dtrt.org/en/developer-reference#addmultisigaddress

[saivann]

@harding I don't know how this would look like, but it's probably possible to allow the page expand more vertically while keeping

tags confined to 600px, without re-organizing tables and losing a 11% of browsers compatibility according to caniuse.com, in case you want to explore this idea. Or otherwise, I'm pretty sure your current layout could be achieved with some workaround around tables. If you'd ask me, I think the "Name Type Presence" rows should have a border.

[harding]

Bah, you're probably right. I'll see if I can do it another way using basic HTML tables.

[saivann]

@harding Beside using HTML directly, isn't there a way to use the "colspan" attribute with markdown? There is also the possibility of generating a separate table for the description, and style it to make it look like a single row of the table it is following. I didn't test it but I think there's good chances this might work.

[harding]

@saivann I've searched, but AFAICT there is no way to use colspan with Kramdown Markdown or even my favorite Markdown, Pandoc.

What I've done for re-imagining this commit is create YAML-powered inline templates that replace the RPC/REST tables, e.g.:

{% itemplate ntpd1 %}
- name: Keys Or Addresses
  type: array
  presence: Required<br>(exactly 1)
  description: An array of strings with each string being a public key or address

- name: →<br>Key Or Address
  type: string
  presence: Required<br>(1 or more)
  description: A public key against which signatures will be checked.  Alternatively, this may be a P2PKH address belonging to the wallet---the corresponding public key will be substituted.  There must be at least as many keys as specified by the Required parameter, and there may be more keys
{% enditemplate %}

That YAML gets fed to the file named _templates/ntpd1.template for formatting.

Right now all I'm trying to do is recreate the current layout perfectly so an HTML diff of the site shows zero changes. I'll PR that (hopefully today) and, if there's agreement, we can merge it.

After that, I can create _templates/ntpd2.template with whatever HTML formatting I want, circumventing any Markdown restrictions. We can probably also find other uses for YAML-powered inline templates elsewhere in the docs (and maybe elsewhere in the site too).

[saivann]

@harding Sounds very interesting!