Draft: RFC: Client/Michelson: Add a command for documenting a Michelson primitive

Context

This is a first shot at michelson-reference#30 (and %Michelson reference: Full integration in michelson-reference) but instead of generating an HTML page it adds a client command for displaying the documentation of any Michelson primitive.

Some examples:

$ ./tezos-client --mode mockup --base-dir /tmp/mockup document michelson primitive  
Display all 141 possibilities? (y or n)
ABS                    HASH_KEY               Pair
ADD                    IF                     PAIR
address                IF_CONS                PAIRING_CHECK
ADDRESS                IF_LEFT                parameter
AMOUNT                 IF_NONE                PUSH
AND                    IMPLICIT_ACCOUNT       READ_TICKET
APPLY                  int                    RENAME
BALANCE                INT                    Right
big_map                ISNAT                  RIGHT
BLAKE2B                ITER                   SAPLING_EMPTY_STATE
bls12_381_fr           JOIN_TICKETS           sapling_state
bls12_381_g1           KECCAK                 sapling_transaction
bls12_381_g2           key                    SAPLING_VERIFY_UPDATE
bool                   key_hash               SELF
bytes                  lambda                 SELF_ADDRESS
CAR                    LAMBDA                 SENDER
CAST                   LE                     set
CDR                    Left                   SET_DELEGATE
chain_id               LEFT                   SHA256
CHAIN_ID               LEVEL                  SHA3
CHECK_SIGNATURE        list                   SHA512
code                   LOOP                   signature
COMPARE                LOOP_LEFT              SIZE
CONCAT                 LSL                    SLICE
CONS                   LSR                    Some
contract               LT                     SOME
CONTRACT               map                    SOURCE
CREATE_ACCOUNT         MAP                    SPLIT_TICKET
CREATE_CONTRACT        MEM                    STEPS_TO_QUOTA
DIG                    MUL                    storage
DIP                    mutez                  string
DROP                   nat                    SUB
DUG                    NEG                    SWAP
DUP                    NEQ                    ticket
EDIV                   never                  TICKET
Elt                    NEVER                  timestamp
EMPTY_BIG_MAP          NIL                    TOTAL_VOTING_POWER
EMPTY_MAP              None                   TRANSFER_TOKENS
EMPTY_SET              NONE                   True
--More--

$ ./tezos-client --mode mockup --base-dir /tmp/mockup document michelson primitive CAST 
CAST: Undocumented
$ ./tezos-client --mode mockup --base-dir /tmp/mockup document michelson primitive CREATE_ACCOUNT 
CREATE_ACCOUNT: Deprecated: Originate an account without script
  Category: deprecated since protocol 005 Babylon (PsBabyM1...)
  History:
    Since protocol 001 AlphaI (PtCJ7pwo...) 
  Typing:
    
  Semantics:
    
$ ./tezos-client --mode mockup --base-dir /tmp/mockup document michelson primitive pair 
(pair ty1 ... tyN): A pair or tuple of values
  Description:
    The type ``pair l r`` is the type of binary pairs composed of a left element of type ``l`` and a right element of type ``r``. A value of type ``pair l r`` is written ``Pair x y`` where ``x`` is a value of type ``l`` and ``y`` is a value of type ``r``.

To build tuples of length greater than 2, right combs have specific optimized operations. For any ``n > 2``, the compact notation ``pair t{0} t{1} ... t{n-2} t{n-1}`` is provided for the type of right combs ``pair t{0} (pair t{1} ... (pair t{n-2} t{n-1}) ...)``. Similarly, the compact notation ``Pair x{0} x{1} ... x{n-2} x{n-1}`` is provided for the right-comb value ``Pair x{0} (Pair x{1} ... (Pair x{n-2} x{n-1})...)``.Right-comb values can also be written using sequences; ``Pair x{0} x{1} ... x{n-2} x{n-1}`` can be written ``{x{0}; x{1}; ...; x{n-2}; x{n-1}}``.
  History:
    Since protocol 001 AlphaI (PtCJ7pwo...)
    Changed in protocol 005 Babylon (PsBabyM1...):
      COMPARE extended to accept pairs and right combs of comparable data
    Changed in protocol 006 Carthage (PsCARTHA...):
      pairs and right combs of comparable data became fully comparable; using them as elements in sets and keys in maps and big maps became possible
    Changed in protocol 008 Edo (PtEdo2Zk...):
      the syntax of right combs was introduced
  Attributes:
    Comparable: yes
    Passable: yes
    Storable: yes
    Pushable: yes
    Packable: yes
    Big map value: yes
    Duplicable: yes
  Typing:
    ctx :- x1 :: ty1
    ....
    ctx :- xN :: tyN
    ------------------------------------------- :: Pair
    ctx :- Pair x1 .... xN :: pair ty1 .... tyN
    
$ ./tezos-client --mode mockup --base-dir /tmp/mockup document michelson primitive DROP 
DROP: Drop the top element of the stack
  Category: stack manipulation
  Description:
    ``DROP`` drops the topmost elements of the stack.

  History:
    Since protocol 001 AlphaI (PtCJ7pwo...) 
  Typing:
    
    --------------------------- :: t_instr_DROP
    ctx :- DROP :: ty1 : A => A
    
  Semantics:
    
    ----------------- :: bs_DROP
    DROP / d : S => S
    
DROP ``n``: Drop the top ``n`` elements of the stack
  Category: stack manipulation
  Description:
    ``DROP n`` drops the `n` topmost elements of the stack. In
particular, ``DROP 0`` is a noop and ``DROP 1`` is equivalent to
``DROP``.

  History:
    Since protocol 005 Babylon (PsBabyM1...) 
  Typing:
    length A = n
    --------------------------- :: t_instr_DROPN
    ctx :- DROP n :: A @ B => B
    
  Semantics:
    length S1 = n
    ----------------------- :: bs_DROPN
    DROP n / S1 ++ S2 => S2

$ ./tezos-client --mode mockup --base-dir /tmp/mockup document michelson primitive DROP --short 
DROP: Drop the top element of the stack
DROP ``n``: Drop the top ``n`` elements of the stack

$ ./tezos-client --mode mockup --base-dir /tmp/mockup document michelson primitive never --short
never: The empty type

$ ./tezos-client --mode mockup --base-dir /tmp/mockup document michelson primitive set
(set cty): An immutable set of comparable values of type ``cty``
  Description:
    Immutable sets of comparable values of type ``cty`` that we note as lists ``{ item ; ... }``, of course with their elements unique, and sorted.
  History:
    Since protocol 001 AlphaI (PtCJ7pwo...) 
  Attributes:
    Comparable: no
    Passable: yes
    Storable: yes
    Pushable: yes
    Packable: yes
    Big map value: yes
    Duplicable: yes
  Typing:
    
    ---------------------------------- :: set_empty
    ctx :- :setlist_Nil: {} :: set cty
    
    ctx :- x :: cty
    ctx :- tl :: set cty
    -------------------------------- :: set_cons
    ctx :- { x ; < tl > } :: set cty

As can be seen on these examples, the output is not perfect:

• newline wrapping is a bit weird
• rst and ott markup are kept (see set and in particular the set_empty typing rule)
• empty section titles are outputted when there is no derivation rule (see CREATE_ACCOUNT)
• when several variants exist for the same primitive it may not be visually clear when --short is not used (see DROP)
• contrary to https://tezos.gitlab.io/michelson-reference/, the examples are not printed
• many other details

Yet, I think that this already brings value and fixing all these points take a lot of time so I would like to get some feedback before improving the output.

Manually testing the MR

• Call tezos-client document michelson primitive <prim> with and without the --short switch on your favorite primitives.
• Compare with https://tezos.gitlab.io/michelson-reference/

Checklist

• Document the interface of any function added or modified (see the coding guidelines)
• Document any change to the user interface, including configuration parameters (see node configuration)
• Provide automatic testing (see the testing guide).
• For new features and bug fixes, add an item in the appropriate changelog (docs/protocols/alpha.rst for the protocol and the environment, the Development Version section of CHANGES.md for everything else).
• Select suitable reviewers using the Reviewers field below.