Commit 9cb0a342 authored by POTTIER Francois's avatar POTTIER Francois

New Web page; updated release script; tweaks in the manual.

parent 06957755
Pipeline #55021 passed with stages
in 25 seconds
......@@ -104,12 +104,12 @@ headache:
BRANCH := release-branch-$(DATE)
# The documentation files $(DOC) are copied to the directory $(LOG) on the
# master branch, for the record. This allows us to easily access all of the
# documentation for earlier versions of Menhir.
# The documentation files $(DOC) are copied to the directory $(RELEASE) on the
# master branch. They are also copied to the directory $(WWW).
DOC := doc/manual.pdf doc/manual.html doc/manual*.png
RELEASE := releases/$(DATE)
WWW := www
# Prior to making a release, one should run [make test],
# then [make pin] and [make -C demos].
......@@ -187,8 +187,12 @@ release:
@ git checkout master
# Commit a copy of the manual *in the master branch* in releases/.
@ echo "Committing a copy of the documentation..."
@ cd $(RELEASE)/doc && git add -f *
@ git commit -m "Saved documentation for release $(DATE)."
@ cd $(RELEASE) && git add -f $(DOC)
@ echo "Publishing the documentation online..."
@ cd $(WWW) && git rm -rf doc
@ cd $(WWW) && cp -r ../$(RELEASE)/doc .
@ cd $(WWW) && git add $(DOC)
@ git commit -m "Saved and published documentation for release $(DATE)."
# Done.
@ echo "Done."
@ echo "If happy, please type:"
......
......@@ -45,8 +45,6 @@
* Send CompCert pull request using the new API (current_state_number)
and MenhirLib.ErrorReports where possible.
* Menhir's Web page should be folded back into the git repo's README.
* Move more of ErrorReports from CompCert to MenhirLib.
In [show], might want to apply [shorten] to the output of [f].
......@@ -110,13 +108,6 @@
exercise *every* production. This could be useful in regression testing,
says Frédéric Bour.
* Dans les avantages de Menhir versus ocamlyacc (dans la doc et
sur la page Web), ajouter le back-end Coq, l'API incrémentale
et l'API d'inspection, les règles anonymes, la gestion fine des
erreurs de syntaxe... Indiquer qu'avec %inline+symboles paramétrés+règles anonymes
on va en fait beaucoup plus loin que LR(1), à condition que la grammaire
après macro-expansion soit encore LR(1).
* Document the fact that (ocaml)yacc and Menhir do not have the same
behavior concerning default reductions (one performs the default
reduction *before* calling the lexer, the other does it the other
......
......@@ -2200,12 +2200,12 @@ This mechanism allows associating pairs of positions with terminal symbols. If
desired, \menhir automatically extends it to nonterminal symbols as well. That
is, it offers a mechanism for associating pairs of positions with terminal or
nonterminal symbols. This is done by making a set of keywords available to
semantic actions (\fref{fig:pos}). Note that these keywords are
semantic actions (\fref{fig:pos}). These keywords are
\emph{not} available outside of a semantic action:
in particular, they cannot be used within an \ocaml header.
Note also that \ocaml's standard library module \texttt{Parsing} is
deprecated. The functions that it offers \emph{can} be called, but will return
dummy positions.
\ocaml's standard library module \texttt{Parsing} is deprecated. The functions
that it offers \emph{can} be called, but will return dummy positions.
We remark that, if the current production has an empty right-hand side, then
\verb+$startpos+ and \verb+$endpos+ are equal, and (by convention) are the end
......@@ -4350,16 +4350,28 @@ value (i.e., either \texttt{true} or \texttt{false}), which indicates whether
% TEMPORARY idéalement, il faudrait documenter la différence de comportement
% sur les réductions par défaut (sur des symboles autres que #).
Roughly speaking, Menhir is 90\% compatible with \ocamlyacc. Legacy \ocamlyacc
grammar specifications are accepted and compiled by Menhir. The resulting
parsers run and produce correct parse trees. However, parsers that explicitly
invoke functions in the module \texttt{Parsing} behave slightly incorrectly.
For instance, the functions that provide access to positions return a dummy
position when invoked by a Menhir parser. Porting a grammar specification from
ocamlyacc to Menhir requires replacing all calls to \texttt{Parsing} with new
Menhir-specific keywords (\sref{sec:positions}).
Here is an incomplete list of the differences between \ocamlyacc and \menhir.
The list is roughly sorted by decreasing order of importance.
\begin{itemize}
\item \menhir allows the definition of a nonterminal symbol to be parameterized by other
(terminal or nonterminal) symbols (\sref{sec:templates}). Furthermore, it offers a library of
standard parameterized definitions (\sref{sec:library}), including options,
sequences, and lists. It offers some support for EBNF syntax,
via the \dquestion, \dplus, and \dstar modifiers.
\item \menhir allows the definition of a nonterminal symbol to be
parameterized (\sref{sec:templates}). A formal parameter can be instantiated
with a terminal symbol, a nonterminal symbol, or an anonymous rule
(\sref{sec:actual}). A library of standard parameterized definitions
(\sref{sec:library}), including options, sequences, and lists, is bundled
with Menhir. EBNF syntax is supported: the modifiers \dquestion, \dplus, and
\dstar are sugar for options, nonempty lists, and arbitrary lists
(\fref{fig:sugar}).
\item \ocamlyacc only accepts LALR(1) grammars. \menhir accepts LR(1) grammars,
thus avoiding certain artificial conflicts.
......@@ -4375,6 +4387,10 @@ The list is roughly sorted by decreasing order of importance.
means that the state of the parser can be saved at any point (at no
cost) and that parsing can later be resumed from a saved state.
\item \menhir offers a set of tools for building a (complete, irredundant)
set of invalid input sentences, mapping each such sentence to a (hand-written)
error message, and maintaining this set as the grammar evolves (\sref{sec:errors:new}).
\item In \ocoq mode, \menhir produces a parser whose correctness and
completeness with respect to the grammar can be checked by Coq (\sref{sec:coq}).
......@@ -4434,9 +4450,9 @@ The list is roughly sorted by decreasing order of importance.
% \item \ocamlyacc allows nonterminal start symbols to start with an uppercase
% letter, and produces invalid \ocaml code in that case. \menhir disallows this.
\item \ocamlyacc ignores semicolons and commas everywhere. \menhir also ignores
semicolons everywhere, but treats commas as significant. Commas are optional
within \dtoken declarations.
\item \ocamlyacc ignores semicolons and commas everywhere. \menhir regards
semicolons and commas as significant, and allows them, or requires them,
in certain well-defined places.
% \item \ocamlyacc ignores multiple definitions of a token, even when two of them are at
% different types. \menhir rejects this.
......
This source diff could not be displayed because it is too large. You can view the blob instead.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Plain HTML site</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<h1>Hello World!</h1>
<p>
This is a simple page.
</p>
</body>
<?xml version="1.0" encoding="UTF8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xml:lang="en" lang="en">
<head>
<style type="text/css">
body { padding: 40px 40px; }
tt { font-family:monospace,monospace; font-size:1em; font-weight:800; }
li { margin-bottom: 10px; }
img.displayed { display: block; margin-left: auto; margin-right: auto }
</style>
<meta charset="utf-8">
<title>Menhir</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<!--------------------------------------------------------------------------->
<img src="affichage.jpg" alt="Your dearest desire: a menhir" class="displayed"/>
<h1>Menhir</h1>
<p>
Menhir is an LR(1) parser generator for
<a href="http://ocaml.org/">OCaml</a>:
it compiles LR(1) grammars down to OCaml code.
</p>
<p>
Menhir replaces
<a href="http://caml.inria.fr/pub/docs/manual-ocaml/lexyacc.html#sec278">ocamlyacc</a>.
Legacy grammars can be compiled by Menhir,
with a few caveats, described in the
<a href="doc/manual.html">reference manual</a>
(<a href="doc/manual.html">HTML</a>;
<a href="doc/manual.pdf">PDF</a>).
</p>
<p>
Menhir is available through <a href="http://opam.ocaml.org/">opam</a>,
OCaml's package manager. Type <tt>opam
install menhir</tt>.
</p>
<p>
Menhir's source code is hosted in this
<a href="https://gitlab.inria.fr/fpottier/menhir/">repository</a>
(<a href="https://gitlab.inria.fr/fpottier/menhir/tags">releases</a>;
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/CHANGES.md">changes</a>).
</p>
<p>
There is a
<a href="https://sympa.inria.fr/sympa/info/menhir">mailing list</a>
for announcements of new releases and discussion of problems, bugs,
feature requests, and so on. Only subscribers can post.
</p>
<p>
Menhir has been designed and implemented by
<a href="http://gallium.inria.fr/~fpottier/">François Pottier</a> and
<a href="http://www.pps.jussieu.fr/~yrg/">Yann Régis-Gianas</a>.
</p>
<p>Menhir has many features that make it superior to the traditional
yacc-style parser generators that many people are familiar with.</p>
<ul>
<li>
Menhir is not restricted to LALR(1) grammars. It accepts <b>LR(1)</b>
grammars, thus avoiding certain artificial conflicts. When a grammar lies
outside this class, Menhir <b>explains conflicts</b> in terms of the
grammar, not just in terms of the automaton. Menhir's explanations are
believed to be understandable by mere humans.
</li><li>
Menhir allows the definition of a nonterminal symbol to be
<b>parameterized</b>. A formal parameter can be instantiated with a
terminal symbol, a nonterminal symbol, or an anonymous rule.
A <b>library</b> of standard parameterized definitions, including options,
sequences, and lists, is bundled with Menhir. EBNF syntax is supported:
the modifiers <tt>?</tt>, <tt>+</tt>, and <tt>*</tt> are
sugar for options, nonempty lists, and arbitrary lists.
Parameterized definitions are expanded away in a straightforward way.
</li><li>
Menhir's <b><tt>&percnt;inline</tt></b> keyword allows indicating that
a nonterminal symbol should be replaced with its definition at every
use site. This offers a second macro-expansion mechanism.
Together, these expansion mechanisms help write concise and elegant
grammars, while avoiding LR(1) conflicts. In other words, they extend
Menhir's expressive power <b>far beyond LR(1)</b>,
while retaining the attractive features of LR(1):
determinism, performance, guaranteed unambiguity.
</li><li>
In <tt>--table</tt> mode only, Menhir supports <b>incremental parsing</b>.
This means that the state of the parser can be saved at any point (at no
cost) and that parsing can later be resumed from a saved state.
Furthermore, Menhir offers an <b>inspection API</b> which allows the
parser's current state and stack to be examined by the user. This opens
the door to a variety of advanced uses, including error explanation, error
recovery, context-dependent lexical analysis, and so on.
</li><li>
Menhir offers a set of tools for building a (complete, irredundant)
set of invalid input sentences, mapping each such sentence to a hand-written
error message, and maintaining this mapping as the grammar evolves.
Thus, <b>a generated parser can produce good syntax error messages</b>.
</li><li>
Menhir has a <a href="https://coq.inria.fr">Coq</a> back-end, which
produces parsers whose correctness and completeness with respect to the
grammar can be <b>verified by Coq</b>.
</li><li>
Menhir offers an <b>interpreter</b> that helps debug grammars interactively.
</li><li>
Menhir allows grammar specifications to be <b>split</b> over multiple files.
It also allows several grammars to share a single set of tokens.
</li><li>
Menhir produces <b>reentrant</b> parsers.
</li><li>
Menhir is able to produce parsers that are <b>parameterized</b> by OCaml modules.
</li><li>
Instead of referring to semantic values via keywords: <tt>$1</tt>, <tt>$2</tt>,
etc., Menhir allows semantic values to be explicitly <b>named</b>. In fact,
Menhir now has
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/doc/new-rule-syntax-blog-post.md">fairly nice syntax</a>
for describing grammars.
</li>
</ul>
</body>
</html>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment