Commit e1b71fbc authored by Michaël Cadilhac's avatar Michaël Cadilhac
Browse files

2005-06-23 Michael Cadilhac <michael.cadilhac@lrde.epita.fr>

	* README: Remove. This file is a copy of `doc/README.txt' in the
	distributed package.
	
	* doc/xml/dev.txt,
	* doc/xml/format.txt: Remove. Deprecated.
	* doc/xml/Makefile.am: Update accordingly.
	
	* doc/tutorial/tutorial.tex,
	* doc/tutorial/macros.tex,
	* doc/tutorial/Makefile.am,
	* doc/tutorial/definitions.tex,
	* doc/tutorial/packages.tex,
	* doc/tutorial: Remove. Deprecated.
	
	* doc/beginner/macros.tex,
	* doc/beginner/help.tex,
	* doc/beginner/Makefile.am,
	* doc/beginner/packages.tex,
	* doc/beginner: Remove. Deprecated.
	
	* doc/Makefile.am,
	* configure.ac: Update accordingly.
	
	* doc/INSTALL.txt,
	* doc/README.txt: Update according to recent changes.
	
	* Makefile.am: Copy `doc/README.txt' and `doc/INSTALL.txt' as
	`README' and `INSTALL' in the root dist directory.
parent 419e482b
2005-06-23 Michael Cadilhac <michael.cadilhac@lrde.epita.fr>
* README: Remove. This file is a copy of `doc/README.txt' in the
distributed package.
* doc/xml/dev.txt,
* doc/xml/format.txt: Remove. Deprecated.
* doc/xml/Makefile.am: Update accordingly.
* doc/tutorial/tutorial.tex,
* doc/tutorial/macros.tex,
* doc/tutorial/Makefile.am,
* doc/tutorial/definitions.tex,
* doc/tutorial/packages.tex,
* doc/tutorial: Remove. Deprecated.
* doc/beginner/macros.tex,
* doc/beginner/help.tex,
* doc/beginner/Makefile.am,
* doc/beginner/packages.tex,
* doc/beginner: Remove. Deprecated.
* doc/Makefile.am,
* configure.ac: Update accordingly.
* doc/INSTALL.txt,
* doc/README.txt: Update according to recent changes.
* Makefile.am: Copy `doc/README.txt' and `doc/INSTALL.txt' as
`README' and `INSTALL' in the root dist directory.
2005-06-23 Louis-Noel Pouchet <louis-noel.pouchet@lrde.epita.fr>
 
* include/vaucanson/algorithms/cut_up.hxx: Fix a bug in cut-up
......
......@@ -30,6 +30,8 @@ dist-hook:
src/Makefile.am src/Makefile.in; do \
grep -v benchs $(srcdir)/$$f > $(distdir)/$$f; \
done
cp $(srcdir)/doc/README.txt $(distdir)/README
cp $(srcdir)/doc/INSTALL.txt $(distdir)/INSTALL
###
### Sanity check.
......
This is Vaucanson, a C++ generic library for weighted finite state
machine.
Please have a look in the doc/ subdirectory for more information and
installation instructions.
......@@ -166,8 +166,6 @@ AC_CONFIG_FILES([
src/benchs/composition/Makefile
src/benchs/derived_terms/Makefile
doc/Makefile
doc/tutorial/Makefile
doc/beginner/Makefile
doc/makefiles/Makefile
doc/xml/Makefile
doc/doc.doxy
......
......@@ -18,7 +18,8 @@ To install Vaucanson on your system, type in the classical sequence at
the command prompt::
./configure
make check
make sanity-check
make check ([1])
make install (as root)
Note that an installation is specific to the compiler used to install
......@@ -26,6 +27,9 @@ it. Indeed, the call to ``./configure`` enables some workarounds and,
consequently, users must compile with the same compiler to avoid
compatibility problems.
[1]: Optional: check the whole library. Note that this process takes
about 1.5 Go of free space (memory swap included) and several hours.
Additional features
-------------------
......
......@@ -2,7 +2,7 @@
#
# $Id$
SUBDIRS = tutorial beginner makefiles xml
SUBDIRS = makefiles xml
include $(srcdir)/Makefile.doc
dist_doc_DATA = ref.tar.gz
......
This is Vaucanson, a C++ generic library for weighted finite state
machine.
===========================
Introduction to Vaucanson
===========================
:Date: 2005-01-15
:Date: 2005-06-23
Vaucanson_, a C++ generic library for weighted finite state machine.
.. _Vaucanson: http://www.lrde.epita.fr/vaucanson
.. _Vaucanson: http://vaucanson.lrde.epita.fr
.. contents::
......@@ -15,9 +19,9 @@ Overview
========
Firstly initiated by Jacques Sakarovitch in 2000, Vaucanson is a
project developed by the Ecole Nationale Supérieure des
Télécommunications [1] and the EPITA Research and Development Laboratory
(LRDE) [2].
project developed by the Ecole Nationale Supérieure des
Télécommunications [1] and the EPITA Research and Development
Laboratory (LRDE) [2].
.. [1] http://www.enst.fr
......@@ -35,20 +39,40 @@ Yet, Vaucanson is an ongoing development project. Therefore
algorithms, data structures and the general architecture are not
totally stable and well tested.
In the ``doc/help`` directory, you can find a short howto to start
programming with Vaucanson. The ``src`` directory contains several
demonstrations, but you can also look at the
``include/vaucanson/algorithms`` to be introduced to the basics of
Vaucanson.
Please send any question or comments to ``vaucanson@lrde.epita.fr``,
and bug reports to ``vaucanson-bugs@lrde.epita.fr``.
Installation
============
See the documentation file ``INSTALL.txt`` for installation
instructions.
Complete installation procedure can be found in ``doc/INSTALL.txt``.
Here is a quick way to install Vaucanson. Type in this sequence at the
command prompt:
./configure
make sanity-check
make install (as root)
This installation requires 220 Mo of free space and takes about 30
minutes on a modern computer.
Note that an installation is specific to the compiler used to install
it. Indeed, the call to ``./configure`` enables some workarounds and,
consequently, users must compile with the same compiler to avoid
compatibility problems.
Using Vaucanson
===============
We are sorry but we do not provide a documentation of Vaucanson.
However Vaucanson comes with several demos. Looking at them is a good
way to see what Vaucanson can do and how it works. Those demos can be
found in the ``src/demos`` directory.
See Also
========
......@@ -68,22 +92,9 @@ There are other sources of interest in the distribution.
- Information about the test suite generation mechanism can be found
in the file ``src/tests/test-suites/README``.
- There are some demonstration programs distributed with the
project. See the ``src/demos`` subdirectory. Some of these are
noteworthy:
- Usage examples in subdirectories ``src/demos/samples`` and
``src/demos/xml/samples``.
- Vaucanson-FSM (``src/demos/fsm/README.txt``) is aimed at providing
an emulation of the FSM toolbox [3].
- Vaucanswig (``src/demos/vaucanswig/doc/README.txt``) is aimed at
providing a dynamic language interpreter to the Vaucanson library.
.. _Doxygen: http://www.doxygen.org
.. [3] http://www.research.att.com/~mohri/fsm/
.. [3] http://www.research.att.com/sw/tools/fsm/
Licence
=======
......@@ -118,4 +129,3 @@ mail addresses follow.
| Paristalie, batiment X, aile Mistral
| F-94270 Le Kremlin Bicêtre cedex
| France
# Makefile.am
#
# $Id$
include $(srcdir)/../Makefile.doc
dist_doc_DATA = help.tex macros.tex packages.tex
help.dvi: $(dist_tex_TEX) $(dist_help_tex_TEX)
help.pdf: $(dist_tex_TEX) $(dist_help_tex_TEX)
dist_doc_DATA += help.dvi help.pdf
MAINTAINERCLEAN = $(dist_doc_DATA)
% help.tex
% $Id$
\documentclass{article}
\include{packages}
\include{macros}
\include{definitions}
\begin{document}
\title{Your first program in Vaucanson}
\maketitle
\tableofcontents
\section{Introduction}
This document is designed to help beginners writing their first
program in Vaucanson. For this purpose, the library provides some c++
headers that contain shortcuts for the basic usage of the library.
\section{How to build an automaton}
The following listing is a valid Vaucanson program:
\begin{code}
1 #include <vaucanson/boolean_automaton.hh>
2 using namespace vcsn::boolean_automaton;
3 int main()
4 {
5 alphabet_t alphabet;
6 alphabet.insert('a');
7 alphabet.insert('b');
8 automaton_t a = new_automaton(alphabet);
9 hstate_t p = a.add_state();
10 hstate_t q = a.add_state();
11 a.set_initial(p);
12 a.set_final(q);
13 a.add_letter_edge(p, q, 'a');
14 a.add_letter_edge(q, p, 'b');
15 tools::dot_dump(std::cout, a, "automaton");
16 }
\end{code}
\begin{list}{$\triangleright$}{}
\item \textbf{line 1 and 2}: To program standard boolean automata (the
so-called acceptors), the user can include this shortcuts' header.
The \verb!using namespace! command makes all shorcuts directly
available. Otherwise, the user has to prefix
\verb!vcsn::boolean_automaton::! to every types and functions.
\item \textbf{line 5}: The first thing to do is to declare the
alphabet we are working with. The type \verb!alphabet_t! is predefined
into the header. We obtain an object instance called \verb!alphabet!.
\item \textbf{line 6 and 7}: \verb!alphabet! is an object instance
that provides services. For example, we can insert 'a' and 'b' into
the alphabet (other services can be consulted in the file
\verb!vaucanson/algebra/concept/alphabets_base.hh!).
\item \textbf{line 8}: The function \verb!new_automaton! defined in
the header takes an alphabet and returns a fresh empty automaton. Here,
we store this automaton into the variable \verb!a!.
\item \textbf{line 9 and 10}: As an object instance, \verb!a! provides
services like the ability to create a new state. This state is
characterized by a handler (concretely, a little integer). In Vaucanson,
every handler for state has the \verb!hstate_t! type.
\item \textbf{line 11 and 12}: \verb!a! can also change the status of
its state. For example, the \verb!set_initial! method mark a state as
initial.
\item \textbf{line 13 and 14}: We can define a transition between two
states labelled by a letter using the method \verb!add_letter_edge!.
The other methods that the user can expect from an automaton are located in
the file: \verb!vaucanson/automata/concept/automata_base.hh!.
\item \textbf{line 15}: Vaucanson provides different way to interact
with the user. For example, we can use the \verb!DOT! format to
display the automaton 'a' with \verb!dotty!.
% FIXME: add reference to the ATT site.
\end{list}
\subsection{How to compile a stand-alone program}
In a shell, if your file is called \verb!automaton.cc! and
if vaucanson is installed on your system,
type the following command:
\begin{verbatim}
% g++ automaton.cc -o automaton
\end{verbatim}
Note: if your Vaucanson is not installed or if it is not installed
into a standard location, add \verb!-I the_vaucanson_directory/include!
to your command.
To execute the program and to display the resulting automaton:
\begin{verbatim}
% ./automaton | dotty -
\end{verbatim}
\section{How to use standard algorithms}
The second step is to test the algorithms of Vaucanson. For this
purpose, the user can also include shortcut header. For example, in
the following code, the program build an automaton and compute its
associated deterministic automaton.
\begin{code}
1 #include <vaucanson/boolean_automaton.hh>
2 #include <vaucanson/standard_algorithms.hh>
3 using namespace vcsn::boolean_automaton;
4 int main()
5 {
6 alphabet_t alphabet;
7 alphabet.insert('a');
8 alphabet.insert('b');
9 automaton_t a = new_automaton(alphabet);
10 hstate_t p = a.add_state();
11 hstate_t q = a.add_state();
12 hstate_t r = a.add_state();
13 a.set_initial(p);
14 a.set_final(r);
15 a.add_letter_edge(q, q, 'a');
16 a.add_letter_edge(p, q, 'a');
17 a.add_letter_edge(q, p, 'b');
18 a.add_letter_edge(q, r, 'b');
19 a.add_letter_edge(r, q, 'a');
20 a.add_letter_edge(r, r, 'b');
21 automaton_t a_det = determinize(a);
22 tools::dot_dump(std::cout, a_det, "det_automaton");
23 }
\end{code}
\begin{list}{$\triangleright$}{}
\item \textbf{line 2}: This header is including several headers present
in the \verb!vaucanson/algorithms! directory.
\item \textbf{line 21}: Algorithms are functions not object instance.
So, they are called as functions.
\end{list}
\end{document}
% macros.tex
%
% $Id$
\newenvironment{code}[1][]%
{\begin{center}
\rule{1cm}{0.02cm} \textit{#1} \rule{1cm}{0.02cm}
\end{center}
\verbatim }
{\endverbatim \begin{center} \rule{2cm}{0.02cm} \end{center}}
% packages.tex
%
% $Id$
\usepackage{makeidx}
\usepackage{verbatim}
\usepackage{url}
\usepackage{ulem}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{palatino}
\usepackage{a4wide}
\usepackage{xspace}
# Makefile.am
#
# $Id$
TEXI2PDF = $(TEXI2DVI) --pdf
# tex_TEX = tutorial.tex
# tutorial_tex_TEX = macros.tex packages.tex definitions.tex
# tutorial.dvi: $(tex_TEX) $(tutorial_tex_TEX)
# $(TEXI2DVI) `test -f '$(tex_TEX)' || echo '$(srcdir)/'`$(tex_TEX)
#tutorial.pdf: $(tex_TEX) $(tutorial_tex_TEX)
# $(TEXI2PDF) `test -f '$(tex_TEX)' || echo '$(srcdir)/'`$(tex_TEX)
docdir = $(datadir)/doc/$(PACKAGE_TARNAME)
# dist_doc_DATA = tutorial.dvi tutorial.pdf tutorial.tex macros.tex \
# packages.tex definitions.tex
CLEANFILES = *.dvi *.aux *blg *.out *.toc *.lot *.tmp
% definitions.tex
%
%
\newcommand\MyDefAlphabet{
\textbf{alphabet:} collection of symbol
}
\ No newline at end of file
% macros.tex
%
% $Id$
\newenvironment{code}[1][]%
{\begin{center}
\rule{1cm}{0.02cm} \textit{#1} \rule{1cm}{0.02cm}
\end{center}
\verbatim }
{\endverbatim \begin{center} \rule{2cm}{0.02cm} \end{center}}
% packages.tex
%
% $Id$
\usepackage{makeidx}
\usepackage{verbatim}
\usepackage{url}
\usepackage{ulem}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{palatino}
\usepackage{a4wide}
\usepackage{xspace}
This diff is collapsed.
include $(srcdir)/../Makefile.doc
dist_doc_DATA = dev.tex dev.pdf dev.html \
format.tex format.pdf format.html
EXTRA_DIST = dev.txt format.txt vaucanson.xsd
EXTRA_DIST = vaucanson.xsd
MAINTAINERCLEANFILES = $(dist_doc_DATA)
==========================================
Vaucanson_ XML development documentation
==========================================
:Author: Valentin David
:Contact: valentin@lrde.epita.fr
:Date: December 2003
This document describe the Vaucanson_ XML developement.
.. _Vaucanson: http://vaucanson.lrde.epita.fr
.. contents::
Modes of use
============
There are three ways to use the Vaucanson XML interface.
- static mode
- dynamic mode
- pseudo-generic mode
Static mode
-----------
This mode use the standard Vaucanson I/O system. An instance of the
``vcsn::xml::xml_loader`` class has to be passed to the
``automaton_loader`` and ``automaton_saver`` functions::
#include <vaucanson/xml/static.hh>
#include <vaucanson/tools/usual.hh>
#include <iostream>
int main()
{
using namespace vcsn;
using namespace vcsn::tools;
using namespace vcsn::xml;
XML_BEGIN;
AUTOMATON_TYPES_EXACT(usual_automaton_t);
automaton_t a;
std::cin >> automaton_loader(a, io::string_out(),
xml::xml_loader());
/* work on a */
std::cout << automaton_saver(a, io::string_out(),
xml::xml_loader());
XML_END;
}
Dynamic mode
------------
This mode able to choose the implementation following the type of the
automaton described in the XML Document.
The automaton is first loaded in a ``xml_automaton_t`` typed
variable. Then the type can be accessed.
Here is an easy to understand example::
#include <vaucanson/xml/dynamic.hh>
#include <vaucanson/tools/usual.hh>
#include <iostream>
int main()
{
xml_automaton_t dynamic_automaton;
std::cin >> dynamic_automaton;
if (x.set().semiring_set() == XmlSet::B) {
AUTOMATON_TYPES_EXACT(usual_automaton_t);
XMLOF(automaton_t) xml_automaton = dynamic_automaton;
automaton_t automaton = xml_automaton;
/* work on automaton */
xml_automaton = automaton;
std::cout << xml_automaton;
}
if ((x.set().semiring_type() == XmlSet::NUMERICAL)
&& (x.set().semiring_set() == XmlSet::Z)) {
AUTOMATON_TYPES_EXACT(weighted_automaton_t);
XMLOF(automaton_t) xml_automaton = dynamic_automaton;
automaton_t automaton = xml_automaton;
/* work on automaton */
xml_automaton = automaton;
std::cout << xml_automaton;
}
return 0;
}
But this example can be written better using generic programming::
#include <vaucanson/xml/dynamic.hh>
#include <vaucanson/tools/usual.hh>
#include <iostream>
template <typename T>
int print_out(typename XMLOF(T) x)
{
using namespace vcsn;
using namespace vcsn::tools;
using namespace vcsn::xml;
AUTOMATON_TYPES_EXACT(T);
automaton_t a = x;
/* work on a */
x = a;
std::cout << x;
return 0;
}
int main()
{
using namespace vcsn;
using namespace vcsn::tools;
using namespace vcsn::xml;
XML_BEGIN;
xml_automaton_t x;
std::cin >> x;
if ((x.set().semiring_type() == XmlSet::NUMERICAL)
&& (x.set().semiring_set() == XmlSet::Z))
return print_out<numerical_automaton_t>(x);
if (x.set().semiring_set() == XmlSet::B)
return print_out<usual_automaton_t>(x);
std::cerr << "Automaton type not dealt" << std::endl;
return -1;
}
Generic mode
------------
The generic mode is very long to compile. So, some constants have to
be set for activating some parts.
``VCSN_XML_GENERIC_WEIGHTED``
Enable "Z" and "R" for semiring.
``VCSN_XML_GENERIC_TRANSDUCERS``
Enable "ratseries" for semiring (no recursion).
``VCSN_XML_GENERIC_CHAR_PAIRS``
Enable "pair" of letters for free monoid.
``VCSN_XML_GENERIC_WEIGHTED_LETTERS``
Enable "weighted" letters for free monoid.
``VCSN_XML_GENERIC_INT_LETTERS``
Enable "integers" for free monoid.
Here is an example::
#define VCSN_XML_GENERIC_WEIGHTED 1
#include <vaucanson/xml/generic.hh>
#include <vaucanson/tools/usual.hh>
#include <iostream>
struct MyData
{
int argc;
char **argv;
MyData(int c, char** v) : argc(c), argv(v) { }
};
template <typename Auto>
struct MyCallBack
{
int operator()(Auto& a, MyData&)
{
using namespace vcsn;