Commit a4788b26 authored by Jacques Sakarovitch's avatar Jacques Sakarovitch Committed by Alexandre Duret-Lutz
Browse files

New version of user's manual. Most of files modified.

parent 0638fc42
......@@ -248,9 +248,10 @@
\newcommand{\tafkit}{\textsc{TAF-Kit}\xspace}
\newcommand{\vcsn}{\textsc{Vaucanson}\xspace}
\def\VcsnVersion{1.4.1}
% \def\VcsnVersion{1.4}
\def\VcsnVrsnOld{1.4}
% \def\VcsnVersion{1.3.9}
\newcommand{\vcsnv}{\vcsn\VcsnVersion\xspace}
\newcommand{\vcsnvo}{\vcsn\VcsnVrsnOld\xspace}
\newcommand{\tafkitv}{\tafkit\VcsnVersion\xspace}
\newcommand{\Vauc}{\vcsn}% for compatibility
\newcommand{\fsmxml}{\textsc{Fsm\,XML}\xspace}
......@@ -265,6 +266,7 @@
\newcommand{\Comt}{\medskip\noindent\textbf{\textsl{Comments}:}\xspace}
\newcommand{\Cave}{\medskip\noindent\textbf{\textsl{Caveat}:}\xspace}
\newcommand{\Exam}{\medskip\noindent\textbf{\textsl{Example}:}\xspace}
\newcommand{\vrglst}{,\e}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\makeatletter
\newcommand{\Cxx}{%
......@@ -423,24 +425,29 @@
%%%
\SetTwClPrm{\TwClOne}%
\SetVCDirectory{figures/}
% \newcommand{\VGIFig}{figures/VGI/}
\newcommand{\VGIFig}{figures/VGI/}
% \ShowFrame
%========== hyphenation===========================
% add words to TeX's hyphenation exception list
\hyphenation{semi-ring}
\hyphenation{simu-la-tion}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\includeonly{%
TFKD-title,%
% TFKD-intro,%
% TFKD-ch0,%
% TFKD-ch1,%
% TFKD-ch1-1,%
% TFKD-ch2,%
% TFKD-bib-ind,%
% % TFKD-chZ,%
% TFKD-chA,%
% TFKD-chVGI,%
% % % TFKD-chB,
% % % TFKD-chC,%
% TFKD-chD,%
TFKD-table,%
TFKD-intro,%
TFKD-ch0-vm,%
TFKD-ch1,%
TFKD-ch1-1,%
TFKD-ch2,%
% TFKD-chZ,%
TFKD-chA,%
TFKD-chVGI,%
% % TFKD-chB,
% % TFKD-chC,%
TFKD-chD,%
% % TFKD-chE,%
TFKD-bib-ind,%
}
\makeindex
\markboth{\leftmark}{\rightmark}
......@@ -450,12 +457,12 @@ TFKD-title,%
%%%%%
\addtocounter{chapter}{-1}
\include{TFKD-title}
\include{TFKD-table}
\include{TFKD-intro}
\include{TFKD-ch0}
\include{TFKD-ch0-vm}
\include{TFKD-ch1}
\include{TFKD-ch1-1}
\include{TFKD-ch2}
\include{TFKD-bib-ind}
\appendix
% \include{TFKD-chZ}
\include{TFKD-chA}
......@@ -464,8 +471,9 @@ TFKD-title,%
% \include{TFKD-chC}
\include{TFKD-chD}
\longonly{\include{TFKD-chE}}
\include{TFKD-bib-ind}
%%%%%%%%%%%%%%%%%%%
\printindex
% \printindex
%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document}
%%%%%%%%%%%%%
......@@ -28,10 +28,9 @@ automaton constructions.
\newblock {\em Theoret. Comput. Sci.\/}~{\bf 155} (1996), 291--319.
\bibitem{ClavEtAl05}
{\sc T. Claveirole, S. Lombardy, S. O'Connor, L.-N. Pouchet, and J.
Sakarovitch. }
{\sc T.~Claveirole, S.~Lombardy, S.~O'Connor, L.-N.~Pouchet, and J.~Sakarovitch. }
\newblock Inside {V}aucanson.
\newblock {\em Proc. CIAA 2005} LNCS~3845, Springer (2005) 117--128.
\newblock {\em Proc. CIAA~2005}, LNCS~3845, Springer (2005) 117--128.
\bibitem{ChamZiad02}
{\sc J.-M. Champarnaud, D. Ziadi. }
......@@ -85,10 +84,15 @@ multiplicity,
(J.~Flum, E.~Gr\"adel, Th.~Wilke, eds)
\newblock Amsterdam Univ. Press, 2007, 457--504.
\bibitem{LombSaka12}
{\sc S.~Lombardy, J.~Sakarovitch. }
\newblock The Removal of Weighted $\varepsilon$-Transitions,
\newblock {\em Proc. CIAA~2012} LNCS~7381, Springer (2012) 345--352.
\bibitem{LombSakaXX}
{\sc S.~Lombardy, J.~Sakarovitch. }
\newblock On the weighted closure problem,
\newblock {\em in preparation\/}.
\newblock {\em in preparation}.
\bibitem{Loth83}
{\sc M.~Lothaire. }
......
\chapter{Getting started}
The \vcsn \textsc{Project} has a web site:
\begin{center}
\code{http://www.vaucanson-project.org}
\end{center}
where all information and documentation on the different components
of the project, including the present manual, can easily be found and
downloaded.
\section{Getting \vcsnv}
Naturally, the version \VcsnVersion\xspace of the \vcsn platform can be downloaded
from the \vcsn \textsc{Project} site.
% The version \VcsnVersion\xspace of the \vcsn platform can be downloaded
% from
\medskip
Alternatively, it can also be found at\\
\PushLine
\code{http://vaucanson.lrde.epita.fr/Vaucanson\VcsnVersion}.
\PushLine
Other previous versions of the \vcsn platform can be downloaded
from \\
\PushLine
\code{http://vaucanson.lrde.epita.fr/}.
\PushLine
% Please note this manual is not meant to be backward compatible with
% \vcsn versions prior to \VcsnVersion.
\Cave
This version \VcsnVersion\xspace is not fully backward compatible
with earlier versions and
this manual is not meant to document the differences with
\vcsn versions prior to \VcsnVersion\xspace (which had never been really
documented).
In one word, no other version than \vcsnv or \vcsn\VcsnVrsnOld\xspace should be used.
\section{Licensing}
\vcsnv is a free software released under the GNU General
Public Licence version 2.
More information on this license is to be found at
\code{http://www.gnu.org/licenses/gpl-2.0.txt} (a copy of
this license is included in each copy of \vcsn in the file
\emph{COPYING}).
Beware that the license for the next versions of \vcsn will
probably be different (although \vcsn will stay an open and free
software).
\section{Prerequisites}
\label{sec:pre-req}%
\begin{description}
\item[\Cpp compiler] \code{G++ 4.x} or later.
\item[\XML] The \XML I/O system is based on the use of the Apache \code{Xerces}
\Cpp library version 2.7 or later (\code{http://apache.org/xerces-c/}). (On
Ubuntu/Debian, install packages with names similar to: \code{libxerces28} and \code{libxerces28-dev},
or \code{libxerces-c3.1} and \code{libxerces-c-dev}),
\Indextt{Xerces}%
\item[\code{Boost}] \code{Boost} provides free peer-reviewed
portable \Cpp source
libraries (On Ubuntu/Debian, install the following packages:
l\code{ibboost-dev}, \code{libboost-serialization-dev}, \code{libboost-graph},
\code{libboost-graph-dev}).
\vcsn is compatible with \code{Boost} versions \code{1.34} or later.
\Indextt{Boost}%
\item[\code{Ncurses}] needed for building \tafkit (On Ubuntu/Debian, install
the following packages: \code{libncurses5}, \code{libncurses-dev}).
\Indextt{Ncurses}%
\item[\code{Graphviz}] The display of automata is made using AT\&T \code{GraphViz}
application (On Ubuntu/Debian, install the following package: \code{graphviz}).
\Indextt{Graphviz}%
\end{description}
\section{Building \vcsn}
\label{sec:bui-ld}%
Detailed information is provided in both \code{INSTALL} and \code{doc/README.txt}
files. The following installation commands will install \vcsn in
'\code{/usr/local}'.
\begin{shell}
$ cd vaucanson-\VcsnVersion
$ ./configure
$ make
$ sudo make install
\end{shell}%
Depending on the architecture, both \code{Boost} and \code{Xerces} might be located
in non-standard directories.
The location of these
libraries may known via the following command:
\begin{shell}
$ whereis boost
\end{shell}%
This command returns the paths to \code{Boost} headers.
These directories are then
specified to the \code{configure} file by means of
two environment variables: \code{CPPFLAGS} for the header files and \code{LDFLAGS}
for the library files.
For instance, if \code{Boost} headers are located
in:\\
'\code{/usr/user\_name/home/my\_path\_to\_boost/include}' and its library
files in:\\
'\code{/usr/user\_name/home/my\_path\_to\_boost/lib}', the
following configure line should be invoked:
\begin{shell}
$ ./configure CPPFLAGS='-I/usr/user\_name/home/my\_path\_to\_boost/include'
LDFLAGS='/usr/user\_name/home/my\_path\_to\_boost/lib'
\end{shell}%
If \vcsn is not installed but only compiled,
the \tafkit binaries are to be found in the directory
'\code{vaucanson-\VcsnVersion/taf-kit/tests/}' (This directory
contains wrappers
around the real \tafkit programs from '\code{vaucanson-\VcsnVersion/taf-kit/src/}'
that enable them to run locally).
\section{Mac\xmd OS\xmd X specifics}
The installation process of \vcsn
and its dependencies on Mac\xmd OS\xmd X may be less straightforward
than onto other Linux systems.
% First, the Mac\xmd OS\xmd X system should be up-to-date before
% going through the rest of the installation process.
First, the \code{macports} software will be used to get all the
prerequisites and should be installed first on the computer
(see \code{http://www.macports.org/}).
A complete guide
to its installation is available from \code{http://guide.macports.org/}.
If \code{macports} is already installed, it should be made up-to date
by synchronising the local port tree with the global \code{macports}
ports by the following command.
\begin{shell}
$ sudo port selfupdate
\end{shell}%
Three libraries are to be installed in order to
build \vcsn (see Prerequisite for details):
\code{Boost},
\code{Xerces}, and
\code{Ncurses}.
\begin{shell}
$ sudo port install ncurses
...
$ sudo port install boost
...
$ sudo port install xercesc
...
$
\end{shell}%
Note that executing each of these commands may take a while
(especially when installing \code{Boost}).
%
By default, \code{macports} will install each of these three
libraries in the \code{/opt/local} directory, which is not standard
with respect to the Unix organisation.
In order to build \vcsn, this directory is therefore to be specified
to the \code{configure} command by the following options:
\begin{shell}
$ ./configure CPPFLAGS='-I/opt/local/include' LDFLAGS='-L/opt/local/lib'
\end{shell}%
Moreover, if the installed version of \code{Boost} is greater than
or equal to~1.44 it is necessary to add another option to the
\code{configure} command:
\begin{shell}
$ ./configure CPPFLAGS='-I/opt/local/include -DBOOST\_SPIRIT\_USE\_OLD\_NAMESPACE'
LDFLAGS='-L/opt/local/lib'
\end{shell}%
The installation is then to be completed by the usual two commands:
\begin{shell}
$ make
$ sudo make install
\end{shell}%
\section{Improving the display quality}
As long as a dedicated graphical interface is not fully operational,
displaying automata is processed by the \code{Graphviz} application, which
is normally launched
in an \code{X11} window.
It is to be acknowledged that the call to \code{Graphviz} by \tafkit
is not well-tuned and that the output is rather poor.
It is not too difficult however to get a rendering of
automata of much better quality (\cf \figur{gra-viz}).
This can be done in three steps and in a slightly different way for
Mac and Linux users.
\subsection{\code{Graphviz} for Mac}
First download the \code{Graphviz} application for Mac from
\code{www.pixelglow.com/graphviz/}.
Although already old and outdated by the \code{2.xx} versions, the
\code{1.13 (v16)} version is recommended as the settings is easier to
handle in that version.
Complete the installation by putting the \code{Graphviz.app} folder
in the \code{Applications} folder.
Second, write the following script in a file called \code{dotty}:
\begin{shell}
#! /bin/sh
if [ "x$1" = x- ]; then
cat >/tmp/tmpdotty$$.dot
open -W -a Graphviz /tmp/tmpdotty$$.dot
rm -f /tmp/tmpdotty$$.dot
else
open -W -a Graphviz "$1"
fi
\end{shell}%
Finally, make this file executable, store it in a folder, and put the
full name of this folder in the \code{PATH} variable before
\code{/usr/local/bin:} and \code{/usr/X11/bin:}.
The appearance of the automata will be determined by fixing the
settings in the interface.
\subsection{\code{Graphviz} for Linux}
For Linux users, the process is almost same except that the program
required is \code{xpdf} and the \code{dotty} script is:
\begin{shell}
#!/bin/sh
f=/tmp/pd$$.png
if test "x$1" = x-; then
dot -Tpdf > $f
else
dot -Tpdf "$@" > $f
fi
xpdf $f
rm -f $f
\end{shell}%
\begin{figure}[ht]
\centering
\includegraphics[scale=0.25]{figures/a1-dotty.ps}
\ee
\includegraphics[scale=0.5]{figures/a1-gv.ps}
\caption{Two versions of the \code{Graphviz} application}
\label{fig:gra-viz}%
\end{figure}
\section{VGI}
The availability of the Graphical User Interface \vgi, developped at
NTU, is one of the novelty of \vcsnv with respect to \vcsnvo.
Every instance of \tafkit has a function \code{gui} that launches
\vgi (\cf \secti{taf-io-fun}).
For this function to work, \tafkit needs to be specified where is \vgi.
Download the \code{vgi.jar} archive from
\code{http://vaucanson-project.org/resources/vgi.jar}, store it in a
folder denoted by \code{/path/to/vgi/folder} in the following.
There is two methods to specify to \vcsn where this archive is
stored: either by setting the environment variable \code{VGIJAR}
with the command:
\begin{shell}
$ export VGIJAR=/path/to/vgi/folder/vgi.jar
\end{shell}
\noindent
or by puting the following script named "\code{vgi}" in a directory of the
path (for instance \code{/usr/local/bin}):
\begin{shell}
#!/bin/sh
exec java -jar /path/to/vgi/folder/vgi.jar "$@"
\end{shell}
\noindent
and making it executable.
A call to the \code{gui} function will then open a window such as the
one shown at \figur{vgi} (\cf \apndx{vgi}).
\begin{figure}[ht]
\centering
\includegraphics[width=3in]{\VGIFig fig14.eps}
\caption{The \vgi window }
\label{fig:vgi}%
\end{figure}
%%%%%%%%%%%
\endinput
\chapter{Administrativia}
\chapter{Getting started}
The \vcsn \textsc{Project} has a web site:
\begin{center}
\code{http://www.vaucanson-project.org}
\end{center}
where all information and documentation on the different components
of the project, including the present manual can easily be found and
downloaded.
\section{Getting \vcsnv}
The version \VcsnVersion\xspace of the \vcsn platform can be downloaded
from \\
Naturally, the version \VcsnVersion\xspace of the \vcsn platform can be downloaded
from the \vcsn \textsc{Project} site.
% The version \VcsnVersion\xspace of the \vcsn platform can be downloaded
% from
Alternatively, it can also be found at\\
\code{http://vaucanson.lrde.epita.fr/Vaucanson\VcsnVersion}
Other previous versions of the \vcsn platform can be downloaded
from \\
\code{http://vaucanson.lrde.epita.fr/}
Please note this manual is not meant to be backward compatible with
\vcsn versions prior to \VcsnVersion.
% Please note this manual is not meant to be backward compatible with
% \vcsn versions prior to \VcsnVersion.
\Cave
This version \VcsnVersion\xspace is not fully backward compatible
with earlier versions and
this manual is not meant to document the differences with
\vcsn versions prior to \VcsnVersion\xspace (which had never been really
documented).
In one word, no other version than \vcsnv or \vcsn\VcsnVrsnOld should be used.
\section{Licensing}
\vcsnv is a free software released under the GNU General
......
......@@ -249,7 +249,7 @@ written in base~2, and then display the quotient\footnote{%
transitions and diplaying it would have been messy.}.
\begin{shell}
$ \kbd{vcsn-char-b -a'01\bslash,' exp-to-aut '1(0+1)*+1(0+1)*,(0+1)(0+1)*' > dec-bin.xml}
$ \kbd{vcsn-char-b -a'01\bslash,' exp-to-aut '1(0+1)*+(1(0+1)*+0),(0+1)(0+1)*' > dec-bin.xml}
$ \kbd{vcsn-char-b quotient dec-bin.xml \bslash| display -}
\end{shell}
......@@ -484,9 +484,9 @@ $ \kbd{vcsn-char-b -ofsm cat b1.xml}
1 1 a 0
1 1 b 0
1 0
$ \kbd{vcsn-char-z -ofsm cat b1.xml \bslash| -ifsm eval - 'bab'}
2
\end{shell}%
% $ \kbd{vcsn-char-z -ofsm cat b1.xml \bslash| -ifsm eval - 'bab'}
% 2
\Cave
The \code{fsm} format is not really implemented in \tafkitv.
......@@ -497,16 +497,28 @@ format within \vcsn.
First, the automata than can be described with the \code{fsm} format
must meet several conditions: one initial state only, labels are
letters (or integers that refer to a symbol table).
Second, \vcsn does not code the weights correctly.
Second, \vcsn does not code the weights correctly for \fst.
It is thus inadequate to try to use the \code{fsm} format for another
automata than `letterized' Boolean automata with a unique initial
state.
The following two examples of commands use the \code{fsm} format for
$\Z$-automata.
The first one gives a correct answer, as the weights are all equal
to~``1'';
the second one demonstrates that \vcsn is not even able to read
correctly the \code{fsm} file it has written.
\begin{shell}
$ \kbd{vcsn-char-z -ofsm cat b1.xml \bslash| -ifsm eval - 'bab'}
2
\end{shell}%
\begin{shell}
$ \kbd{vcsn-char-z -ofsm cat c1.xml}
0 1 1 0
0 0 0+1 0
1 1 ({2} 0)+({2} 1) 0
1 1 (\{2\} 0)+(\{2\} 1) 0
1 0
$ \kbd{vcsn-char-z -ofsm cat c1.xml | vcsn-char-z -ifsm -ofsm cat -}
0 1 e 0
......@@ -540,7 +552,7 @@ By default, rational expressions are \emph{read} as strings given on
the \emph{command line},
and \emph{output} as strings on the \emph{standard output}.
Both can be diverted in the Unix way, but a \emph{string} written in a file
cannot be read by \tafkit in this file.
cannot be read by \tafkit directly in this file (\cf \sbsct{fct-cat-E}).
\begin{shell}
$ \kbd{vcsn-char-b -aab cat-E '(a+b(a(b)*a)*b)*'}
......@@ -579,14 +591,6 @@ $ \kbd{vcsn-char-b -ixml cat-E exp.xml}
(a+b.(a.b*.a)*.b)*
\end{shell}%$
\longonly{%
\begin{ComVd}{110515}
Contrarily to what had been written in an earlier version of this
document, ``rational expressions will \emph{not} be read or written as text string if an
unsupporting format is requested'' but very logically the reading or
writing in that format will be denied..
\end{ComVd}%
}%
\subsubsection{Word formats}
......@@ -598,13 +602,17 @@ command line, and written on the standard output.
\Cave
Although \emph{words} are, from a formal point of view, a (simple)
instance of a rational expression, \tafkitv handles them as objects
of different and uninterchangeable types.
of different and uninterchangeable types (\cf \sbsct{evl-wrd}).
We come back to the subject in the next section.
\longonly{%
\begin{ComVd}{110515}
It is not clear whether there exists indeed a command which
The command \Fct{eval} reads a word, and not an expression.
It does not seem that there exists indeed a command which
outputs a `word' (and not an automaton or an expression).
This will be reworked in the framework where there will be two
kinds of expressions.
\end{ComVd}%
}%
......@@ -621,6 +629,11 @@ $ \kbd{vcsn-char-z eval c1.xml '101101'}
The way they are input, as strings as well, as part of a rational
expression, is described in the next section.
In one case (in two similar cases indeed), weights will be input as
argument of a function and not as part of a rational expression. They
will be written as strings as well, which will raise some problem
(\cf \sbsct{aut-sta-ext-mul}).
\subsubsection{Boolean result formats}
\label{ssc:boo-res-for}
......@@ -747,7 +760,7 @@ by other programs.
\longonly{%
\begin{ComVd}{110723}
The \code{-D} option yields a \code{dot} file which is correctly
dispalyed on the screen but when exported as a \code{ps} file and
displayed on the screen but when exported as a \code{ps} file and
incorporated in the \tex output sends the \code{pstopdf} command into
error.
\end{ComVd}%
......@@ -795,10 +808,11 @@ Charge id: <name> total self calls self avg. total avg.
\longonly{%
\begin{ComVd}{110529}
I report some of my experiments and findings about \code{cbs} in
a special appendix which will not appear in the distributed
Some experiments and findings about \code{cbs} are reported at
\apndx{ben-fun-vcs},
an appendix which does not appear in the distributed
version of the \tafkit documentation.
It should help us to profile the version of \code{cbs} in \vcsn2.
It should help us to profile the version of \code{cbs} in \vcsn~2.
\end{ComVd}%
}%
......@@ -941,46 +955,18 @@ is rewritten as indicated on the right.
(\{k\}\Ed)\{h\} \Rightarrow \{k\}(\Ed\{h\})
\tag{$\mathbf{A}_{\K}$}
\\[.7ex]
\und\{k\} \Rightarrow \{k\}\und \ee
% \und\{k\} \Rightarrow \{k\}\und \ee
\Ed.(\{k\}\und) \Rightarrow \Ed\{k\} \ee
(\{k\}\und).\Ed \Rightarrow \{k\}\Ed
\tag{$\mathbf{U}_{\K}$}\\[.7ex]
\und \{k\}\Rightarrow \{k\}\und \ee x\{k\}\Rightarrow \{k\}x
\tag{$\mathbf{C}_{\mathsf{at}}$}
\label{equ:c-at}
\end{gather}
\caption{The trivial identities}
\label{tab:tri-ide}%
\end{table}
\longonly{%
\begin{ComVd}{110723}
La dŽfinition de l'identitŽ
correspond ˆ ce qui est implŽmentŽ dans
Elle est due ˆ un quiproquo sur la signification du mot `atome':
\emph{atome} d'une expression rationnelle et \emph{atome} des
\code{labels-are-atoms} pour la dŽfinition des \emph{kinds} dans
\vcsn~2.xx.
Une dŽfinition plus naturelle serait:
% \begin{equation*}