Author: tziade
Date: Sat Apr 1 22:46:49 2006
New Revision: 2756
Modified:
cookbook/trunk/recipe50.en.tex
Log:
finished translation
Modified: cookbook/trunk/recipe50.en.tex
==============================================================================
--- cookbook/trunk/recipe50.en.tex (original)
+++ cookbook/trunk/recipe50.en.tex Sat Apr 1 22:46:49 2006
@@ -49,30 +49,27 @@
Using this document, she creates the code following these steps:
\begin{itemize}
-\item Transcripting in a reST document (doctest) the specifications;
+\item Translating in a reST document (doctest) the specifications;
\item inserting code examples, that fullfills the features asked;
\item coding the underlying code, so the examples in the document
works for real.
\end{itemize}
-\subsection*{Transcripting the need into a doctest file}
-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+\subsection*{Translating the need into a doctest file}
-Transcrire en doctest les besoins exprim�s se fait en synth�tisant au maximum
le
-cahier des charges, et en d�crivant la structure du paquet qui va �tre
-d�velopp�.
-
-Prenons l'exemple d'un module en charge de r�cup�rer des flux RSS pour les
-stocker dans des objets Python persistants, puis les rendre affichables dans
-l'application. Le d�veloppeur d�cide d'organiser son paquet en trois modules:
+Translating in doctests the needs is done by summarrizing the specifications,
+and by describing the future package structure.
+
+Let's code for example a package that handles the retrieval of RSS feeds to
+store them in persistent Python objects, then provide web views. The developer
+decides to organize the package in three modules:
\begin{itemize}
-\item \code{rssfetcher.py}: module en charge de la r�cup�ration des flux RSS;
-\item \code{rssobject.py}: module en charge de la cr�ation et du stockage
-des donn�es;
-\item \code{rssview.py}: module en charge de l'affichage des donn�es.
+\item \code{rssfetcher.py}: module for RSS retrieval;
+\item \code{rssobject.py}: module for creating and storing data;
+\item \code{rssview.py}: module for viewing data.
\end{itemize}
-\noindent Il commence par �crire quatre fichiers doctests, qui expriment cette
+\noindent She starts to write four doctests files, that shows the future code
structure:
\begin{itemize}
\item \code{README.txt}
@@ -81,55 +78,51 @@
\item \code{rssview.txt}
\end{itemize}
-Le fichier \code{README.txt} d�crit en quelques phrases l'objectif du paquet,
-et pr�sente sa structure.
+The \code{README.txt} file describe in a few sentences the package goal, and
+present its structure.
-\codetitle{Fichier README.txt}
+\codetitle{README.txt file:}
\begin{Verbatim}
rssreader
=========
-Ce paquet permet de pr�senter des flux rss. Il est organis� en trois
-composants:
+This package knows how to display RSS feeds. It is organized in three modules.
-- rssfetcher: sait lire un flux RSS 1.0
-- rssobject: stocke le flux et fourni des m�thodes d'acc�s
-- rssview: sait afficher un flux dans le navigateur
+- rssfetcher: knows how to read RSS 1.0 feeds
+- rssobject: store the feeds and provides accessors
+- rssview: know how to display a feed in the browser
\end{Verbatim}
-\noindent Chaque module est pr�sent� � son tour dans un doctest.
+\noindent Each module then has its own doctest file.
-\codetitle{Fichier rssfetcher.txt}
+\codetitle{rssfetcher.txt file:}
\begin{verbatim}
rssfetcher
==========
-Le module rssreader transforme un fichier XML au format RSS 1.0
-vers une structure Python exploitable. Il est invoqu� avec l'URL
-d'un flux et renvoi une liste contenant les entr�es du flux.
+rssfetcher module transforms a RSS 1.0 XML file into a Python usable structure.
+It is called with the feed URL and returns a list with the feed entries.
\end{verbatim}
-A ce stade, le d�veloppeur n'a pas encore �crit de code, mais
-dispose d'une sp�cification technique et architecturelle exploitable.
+At this point the developer didn't write any code, but has a first draft of
+the package structure and technical specifications. This step reveals sometimes
+some incoherences in the needs.
-\subsection*{Ins�rer des exemples de codes}
+\subsection*{Inserting code examples}
-Sur la base de ces fichiers textes, le d�veloppeur peut commencer
-� pr�parer le d�veloppement des modules, en explicitant la face
-visible de ces derniers, c'est � dire les API qui seront utilis�es
-dans d'autres modules.
+Using these text files, the developer can start to define each module high
level
+public elements, that will be used by other modules.
-\codetitle{Modification du fichier rssfetcher.txt}
+\codetitle{Changing rssfetcher.txt:}
\begin{verbatim}
rssfetcher
==========
-Le module rssfetcher transforme un fichier XML au format RSS 1.0
-vers une structure Python exploitable. Il est invoqu� avec l'URL
-d'un flux et renvoi une liste contenant les entr�es du flux.
+rssfetcher module transforms a RSS 1.0 XML file into a Python usable structure.
+It is called with the feed URL and returns a list with the feed entries.
-Il fourni une fonction `fetchFeed(source)` qui renvoie une structure Python
-en fonction d'une URL ou d'un fichier ::
+It provides a `fetchFeed(source)` function that returns a Python structure,
+given an URL or a file ::
>>> from rssfetcher import fetchFeed
>>> fetchFeed('tests/rss.xml')
@@ -137,39 +130,42 @@
\end{verbatim}
\begin{codenotes}
-\item Le paquet doit pr�voir dans un sous r�pertoire un fichier
-�chantillon \code{rss.xml}, contenant un flux utilis� pour les tests.
+\item At this point the package will need a \code{rss.xml} file to be used as a
+sample for tests.
\end{codenotes}
-\noindent Ce principe est appliqu� pour l'ensemble des modules du paquet,
-susceptibles de fournir des fonctionnalit�s.
+\noindent This principle is used for all modules that might provide public
+functionalities.
-\subsection*{D�velopper les fonctionnalit�s}
+\subsection*{Coding functionalities}
-Le doctest pr�c�dent ne peut bien s�r fonctionner que si l'impl�mentation
-est r�alis�e. Le d�veloppeur con�oit donc le module \code{rssfetcher.py}
-jusqu'� ce que le test du doctest passe. Ce d�veloppement n�cessitera
-certainement la cr�ation d'autres tests unitaires, qui seront
-con�us classiquement dans des classes dans le sous-r�pertoire de \code{tests}.
-
-Lorsque tous les modules sont con�us, \code{README.txt} contient un exemple
-complet d'utilisation, qui simule g�n�ralement quelques directives ZCML
-et quelques �changes avec le publisher.
-
-\section*{Maintenir et faire �voluer le code}
-
-L'�volution du paquet, que ce soit dans le cadre d'une correction, ou
-d'une modification, doit se faire de la m�me mani�re: les fichiers textes
-sont revus en premiers, puis le code est modifi� en cons�quence.
-
-Les corrections de bogues sont trait�s d'une mani�re particuli�re:
-un test unitaire qui reproduit le probl�me est ajout� dans les classes de
-tests, et le code invoqu� corrig�. Ajouter ces tests dans les doctests
-d�nature leur objectif secondaire: servir de documentation.
-
-Cependant, si il est explicitement demand� que les bugfix soient document�s,
-et facilement lisibles, un doctest \code{bugfix.txt} peut �tre ajout�.
-Ce n'est pas le cas pour Zope 3 par exemple, car le couple tracker+svn fourni
-une bonne tracabilit� des bugfix.
+The previous doctest cannot work until the functionalitie is really
+implemented. The developer codes the \code{rssfetcher.py} module until
+the tests passes. By doing so, new tests will certainly be done, but
+in classical unit tests in a \code{tests} subfolder. This will avoid adding
+tests in the doctests files and make them unreadable with implementation
+level matters.
+
+When all modules are done, \code{README.txt} needs to contain a full example
+on how to use the feature, and will probably have to simulate a few ZCML
+directives and a few data exchanges with the publisher, through a functional
+doctest.
+
+\section*{Maintaining and making the code evolve}
+
+The package evolution, for a correction or a modification, needs to be
+done the same way: texte files are first reviewed, then the code is
+consequently modified.
+
+Bug fixes are treated in a particular way: a unit test that reproduces
+the problem is added in the unit tests modules, and the incriminated
+code corrected. Those tests aren't to be added in doctests, to avoid
+making them unreadable and lose their first intent: being part of the
+documentation.
+
+On the other hand, if it's explicitely asked that bugfixes should be
+documented and easily readable, a \code{bugfix.txt} can be added to collect
+them. This is not the case for such project as Zope 3 because they provide
+enough feedback on bugfixes with the tracker and the subversion system.
\end{solution}
\end{document}
--
http://lists.nuxeo.com/mailman/listinfo/z3lab-checkins
