First, before getting to the topic, I must whine about my dislike of table syntaxes of reStructuredText and Markdown, their table syntaxes are not good in term of the number of additions and deletions in revising. When you need to add more text into a cell, it’s most likely ending up updating all rows. Yes, both have simple table syntax, but, well, by the look of them, I’d prefer not using table at all than using simple table syntax. In fact, none of markup languages does make me happy. If I could find one using key-value, then it probably would be my prefer syntax. Imagining that you could add a new column without fixing entire table.

Okay, now, starting the point. This came to my attention when I am trying to edit a table for command-line options, let’s take a look at final result:

option description note
-f --foo Foo (f)
-b --bar Bar (b)
(f)
Foo
(b)
Bar

The source code is:

+--------------------+-------------+------+
| option             | description | note |
+========+===========+=============+======+
| ``-f`` | ``--foo`` | Foo         | \(f) |
+--------+-----------+-------------+------+
| ``-b`` | ``--bar`` | Bar         | \(b) |
+--------+-----------+-------------+------+

\(f)
  Foo

\(b)
  Bar

Originally, I was using the following for note reference points, that is with ordered list:

``(1)``
``(2)``

1. Foo
2. Bar

But as I reviewing, it came to my mind, this would be prone to changes when you need to insert a new option anywhere before the last point. Even, from where I learned the \(x) approach, it would still be subjected to changes when using ordered list. So, using a short option like abbreviation would work best.

The list is with letters probably wouldn’t be changed lightly, and the order of rows and lists are easy to maintain together. You can order the definition list by alphabets if you want, but I would like to keep it in the same order as in the table.