84 lines
5.4 KiB
Markdown
84 lines
5.4 KiB
Markdown
|
---
|
|||
|
|
title: "I Don't Like Coq's Documentation"
|
|||
|
|
date: 2021-11-24T21:48:59-08:00
|
|||
|
|
draft: true
|
|||
|
|
tags: ["Coq"]
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
Recently, I wrote an article on [Formalizing Dawn's Core Calculus in Coq]({{< relref "./coq_dawn.md" >}}).
|
|||
|
|
One of the proofs (specifically, correctness of \\(\\text{quote}_3\\)) was the best candidate I've ever
|
|||
|
|
encountered for proof automation. I knew that proof automation was possible from the second book of Software
|
|||
|
|
Foundations, [Programming Language Foundations](https://softwarefoundations.cis.upenn.edu/plf-current/index.html).
|
|||
|
|
I went there to learn more, and started my little journey in picking up Coq's `Ltac2`.
|
|||
|
|
|
|||
|
|
Before I go any further, let me say that I'd self-describe as an "advanced beginner" in Coq, maybe "intermediate"
|
|||
|
|
on a good day. I am certainly far from a master. I will also say that I am quite young, and thus possibly spoiled
|
|||
|
|
by the explosion of well-documented languages, tools, and libraries. I don't frequently check `man` pages, and I don't
|
|||
|
|
often read straight up technical manuals. Maybe the fault lies with me.
|
|||
|
|
Nevertheles, I feel like I am where I am in the process of learning Coq
|
|||
|
|
in part because of the state of its learning resources.
|
|||
|
|
As a case study, let's take my attempt to automate away a pretty simple proof.
|
|||
|
|
|
|||
|
|
### Grammars instead of Examples
|
|||
|
|
I did not specifically remember the chapter of Software Foundation in which tactics were introduced.
|
|||
|
|
Instead of skimming through chapters until I found it, I tried to look up "coq custom tactic". The
|
|||
|
|
first thing that comes up is the page for `Ltac`.
|
|||
|
|
|
|||
|
|
After a brief explanation of what `Ltac` is, the documentation jumps straight into the grammar of the entire
|
|||
|
|
tactic language. Here' a screenshot of what that looks like:
|
|||
|
|
|
|||
|
|
{{< figure src="ltac_grammar.png" caption="The grammar of Ltac from the Coq page." class="large" alt="A grammar for the `Ltac` language within Coq. The grammar is in Backus–Naur form, and has 9 nonterminals." >}}
|
|||
|
|
|
|||
|
|
Good old Backus-Naur form. Now, my two main areas of interest are programming language theory and compilers, and so I'm no stranger to BNF. In fact, the first
|
|||
|
|
time I saw such a documentation page (most pages describing Coq language feature have some production rules), I didn't even consciously process that I was looking
|
|||
|
|
at grammar rules. However, and despite CompCert (a compiler) being probably the most well known example of a project in Coq, I don't think that Coq is made _just_
|
|||
|
|
for people familiar with PLT or compilers. I don't think it should be expected for the average newcomer to Coq (or the average beginner-ish person like me) to know how to read production rules, or to know
|
|||
|
|
what terminals and nonterminals are. Logical Founadtions sure managed to explain Gallina without resorting to BNFs.
|
|||
|
|
|
|||
|
|
And even if I, as a newcomer, know what BNF is, and how to read the rules, there's another layer to this specification:
|
|||
|
|
the precedence of various operators is encoded in the BNF rules. This is a pretty common pattern
|
|||
|
|
for writing down programming language grammars; for each level of operator precedence, there's another
|
|||
|
|
nonterminal. We have `ltac_expr4` for sequencing (the least binding operator), and `ltac_expr3` for "level 3 tactics",
|
|||
|
|
`ltac_expr2` for addition, logical "or", and "level 2 tactics". The creators of this documentation page clearly knew
|
|||
|
|
what they were getting at here, and I've seen this pattern enough times to recognize it right away. But if you
|
|||
|
|
_haven't_ seen this pattern before (and why should you have?), you'll need to take some time to decipher the rules.
|
|||
|
|
That's time that you'd rather spend trying to write your tactic.
|
|||
|
|
|
|||
|
|
The page could just as well have mentioned the types of constructs in `Ltac`, and given a table of their relative precedence.
|
|||
|
|
This could be an opportunity to give an example of what a program in `Ltac` looks like. Instead, despite having seen all of these nonterminals,
|
|||
|
|
I still don't have an image in my mind's eye of what the language looks like. And better yet, I think that the grammar's incorrect:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
ltac_expr4 ::= ltac_expr3 ; ltac_expr3|binder_tactic
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
The way this is written, there's no way to sequence (using a semicolon) more than two things. The semicolon
|
|||
|
|
only occurs on level four, and both nonterminals in this rule are level three. However, Coq is perfectly happy
|
|||
|
|
to accept the following:
|
|||
|
|
|
|||
|
|
```Coq
|
|||
|
|
Ltac test := auto; auto; auto.
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
In the `Ltac2` grammar, this is written the way I'd expect:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
ltac2_expr ::= ltac2_expr5 ; ltac2_expr
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Let's do a quick recap. We have an encoding that requires a degree of experience with grammars and
|
|||
|
|
programming languages to be useful to the reader, _and_ this encoding
|
|||
|
|
{{< sidenote "right" "errors-note" "leaves room for errors," >}}
|
|||
|
|
Here's a question to ponder: how come this error has gone unnoticed? Surely
|
|||
|
|
people used this page to learn <code>Ltac</code>. I believe that part of the reason is
|
|||
|
|
pattern matching: an experienced reader will recognize the "precedence trick", and quickly
|
|||
|
|
scan the grammar levels to estblish precedence. The people writing and proofreading this
|
|||
|
|
documentation likely read it this way, too.
|
|||
|
|
{{< /sidenote >}}
|
|||
|
|
errors that _actually appear in practice_.
|
|||
|
|
{{< sidenote "left" "achilles-note" "We have a very precise, yet incorrect definition." >}}
|
|||
|
|
Amusingly, I think this is very close to what is considered the achilles heel of formal verification:
|
|||
|
|
software that precisely adheres to an incorrect or incomplete specification.
|
|||
|
|
{{< /sidenote >}}
|
|||
|
|
Somehow, "a sequence of statements separated by a semicolon" seems like a simpler explanation.
|