Decide on documentation format

[taviso]

We should decide on a format to store the documentation before it gets too big to manage by hand!

[angea]

Is it going to be so big though?
I feel that only the Macro and Crypt dialog are really missing among the last remaining complex things...

Do you want to keep it as a long list or eventually a clickable reference over multiple page, that we could reference in recipes ?

[taviso]

You've got a point, maybe it won't be an issue!

I think it would be good if you click on a key and jumps to the documentation for that, and then other pages can link to the keys (like tutorials or something). It's not urgent though, those docs don't exist yet 😄

[taviso]

I had a look at pandoc, it's an option. For example this input:

$ cat test.md 

+-----------------+-------------------------------------------------------------------+
| Shortcut        | Description                                                       |
+=================+===================================================================+
| [*]{.shortcut}  | Mark/unmark a block, this is like visual mode in Vim, it selects  |
|                 | a contiguous region of bytes. Press * to start a block under      |
|                 | cursor, then use the cursor keys to move to  extend the block.    |
|                 | Press * again to mark the end. Only one block can be active at a  |
|                 | time.                                                             |
+-----------------+-------------------------------------------------------------------+

Generates this output:

$ pandoc test.md 
<table>
<colgroup>
<col width="20%" />
<col width="79%" />
</colgroup>
<thead>
<tr class="header">
<th>Shortcut</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p><span class="shortcut">*</span></p></td>
<td><p>Mark/unmark a block, this is like visual mode in Vim, it selects a contiguous region of bytes
. Press * to start a block under cursor, then use the cursor keys to move to extend the block. Press
 * again to mark the end. Only one block can be active at a time.</p></td>
</tr>
</tbody>
</table>

It might be easier to maintain, keep all the shortcuts in seperate files, then use pandoc to build the final output. What do you think?

[angea]

I use Pandoc and markdown myself already, so why not - are the columns of fixed width ?