coqdoc: a documentation tool for Coq

Jean-Christophe Filliâtre
`http://www.lri.fr/~filliatr/coqdoc`

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 L^AT_EX 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.

coqdoc uses different faces for identifiers and keywords. For the L^AT_EX output, it uses mathematical symbols for some Coq tokens; here are the correspondences:

`->`	®	`<-`	¬	`*`	×
`<=`	£	`>=`	³	`=>`	Þ
`<>`	¹	`<->`	«	`\|-`	\|-
`\/`	or	`/\`	&	`~`	not

Sections.

Sections are introduced by 1 to 4 leading stars (i.e. at the beginning of the line). On star is a section, two stars a sub-section, etc. The section title is given on the remaining of the line. Example:

    (** * Well-founded relations
  
        In this section, we introduce...  *)

Lists.

List items are introduced by 1 to 4 leading dashes. Deepness of the list is indicated by the number of dashes. List ends with a blank line. Example:

    This module defines
        - the predecessor [pred]
        - the addition [plus]
        - order relations:
          -- less or equal [le]
          -- less [lt]

Rules.

More than 4 leading dashes produce an horizontal rule.

Escapings to L^AT_EX and HTML.

Pure L^AT_EX or HTML material can be inserted using the following escape sequences:

$...LaTeX stuff...$ inserts some L^AT_EX material in math mode. Copied in italics in HTML output.
%...LaTeX stuff...% inserts some L^AT_EX material. Copied as is in HTML output.
#...HTML stuff...# inserts some HTML material. Simply discarded in L^AT_EX output.

Verbatim.

Verbatim material is introduced by a leading << and closed by >>. Example:

Here is the corresponding caml code:
<<
  let rec fact n = 
    if n <= 1 then 1 else n * fact (n-1)
>>

3 Usage

coqdoc is invoked on a shell command line as follows:

coqdoc <options and files>

Any command line argument which is not an option is considered to be a file (even if it starts with a -). Coq files are identified by the suffixes .v and .g and L^AT_EX files by the suffix .tex.

HTML output: This is the default output. One HTML file is created for each Coq file given on the command line, together with a file index.html (unless option -no-index is passed). The HTML pages use a style sheet named style.css. Such a file is distributed with coqdoc.
L^AT_EX output: A single L^AT_EX file is created, on standard output. It can be redirected to a file with option -o. The order of files on the command line is kept in the final document. L^AT_EX files given on the command line are copied `as is' in the final document . DVI and PostScript can be produced directly with the options -dvi and -ps respectively.

Command line options

--html: Selects a HTML output.
--latex: Selects a L^AT_EX output.
--dvi: Selects a DVI output.
--ps: Selects a PostScript output.
-o file, --output file: Redirects the output into the file `file' (meaningless with -html).
-s , --short: Do not insert titles for the files. The default behavior is to insert a title like ``Module Foo'' for each file.
-t string, --title string: Set the document title.
--no-preamble: Suppresses the header and trailer of the final document. Thus, you can insert the resulting document into a larger one.
--no-index: Do not output the index.
--multi-index: Generate one page for each category and each letter in the index, together with a top page index.html.
--glob-from file: Make references using Coq globalizations from file file. (Such globalizations are obtained with Coq option -dump-glob).
-R dir coqdir: Map physical directory dir to Coq logical directory coqdir (similarly to Coq option -R).
-p string, --preamble string: Insert some material in the L^AT_EX preamble, right before \begin{document} (meaningless with -html).
--vernac-file file, --tex-file file: Considers the file `file' respectively as a .v (or .g) file or a .tex file.
--files file: Read file names to process in file `file' as if they were given on the command line. Useful for program sources splitted in several directories. See FAQ.
-q, --quiet: Be quiet. Do not print anything on standard error output except errors.
-h, --help: Gives a short summary of the options and exits.
-v, --version: Prints the version and exits.

4 The `coqdoc` L^AT_EX style file

In case you choose to produce a document without the default L^AT_EX preamble (by using option --no-preamble), then you must insert into your own preamble the command

\usepackage{coqdoc}

Then you may alter the rendering of the document by redefining some macros:

coqdockw, coqdocid

The one-argument macros for typesetting keywords and identifiers. Defaults are sans-serif for keywords and italic for identifiers.

For example, if you would like a slanted font for keywords, you may insert

     \renewcommand{\coqdockw}[1]{\textsl{#1}}

anywhere between \usepackage{coqdoc} and \begin{document}.

coqdocmodule

One-argument macro for typesetting the title of a .v file. Default is

\newcommand{\coqdocmodule}[1]{\section*{Module #1}}

and you may redefine it using \renewcommand.

5 FAQ

This document was translated from L^AT_EX by H^EV^EA.