coqdoc: a documentation tool for Coq
Table of Contents
1 Introduction
coqdoc is a documentation tool for the proof assistant
Coq, similar to javadoc or ocamldoc.
The task of coqdoc is
-
to produce a nice LATEX and/or HTML document from the Coq
sources, readable for a human and not only for the proof assistant;
- to help the user navigating in his own (or third-party) sources.
2 Principles
Documentation is inserted into Coq files as special comments.
Thus your files will compile as usual, whether you use coqdoc or not.
coqdoc presupposes that the given Coq files are well-formed (at
least lexically). Documentation starts with
(**, followed by a space, and ends with the pending *).
The documentation format is inspired
by Todd A. Coram's Almost Free Text (AFT) tool: it is mainly
ASCII text with some syntax-light controls, described below.
coqdoc is robust: it shouldn't fail, whatever the input is. But
remember: ``garbage in, garbage out''.
Coq material inside documentation.
Coq material is quoted between the
delimiters [ and ]. Square brackets may be nested,
the inner ones being understood as being part of the quoted code (thus
you can quote a term like [x:T]u by writing
[[x:T]u]). Inside quotations, the code is pretty-printed in
the same way as it is in code parts.
Pre-formatted vernacular is enclosed by [[ and
]]. The former must be followed by a newline and the latter
must follow a newline.
Pretty-printing.
coqdoc uses different faces for identifiers and keywords.
The pretty-printing of Coq tokens (identifiers or symbols) can be
controlled using the following command:
(** printing token %...LATEX...% #...HTML...# *)
It gives the LATEX and HTML texts to be produced for the given Coq
token. One of the LATEX or HTML text may be ommitted, causing the
default pretty-printing to be used for this token.
The printing for one token can be removed with
(** remove printing token *)
Initially, the pretty-printing table contains the following mapping:
-> |
® |
|
<- |
¬ |
|
* |
× |
|
<= |
£ |
|
>= |
³ |
|
=> |
Ž |
|
<> |
¹ |
|
<-> |
« |
|
|- |
|- |
|
\/ |
or |
|
/\ |
& |
|
~ |
not |
|
Any of these can be overwritten or suppressed using the
printing commands.
Important note: the recognition of tokens is done by a (ocaml)lex
automaton and thus applies the longest-match rule. For instance,
->