Author: tziade
Date: Fri Mar 24 23:31:18 2006
New Revision: 2714
Modified:
cookbook/trunk/recipe48.en.tex
Log:
finished translation
Modified: cookbook/trunk/recipe48.en.tex
==============================================================================
--- cookbook/trunk/recipe48.en.tex (original)
+++ cookbook/trunk/recipe48.en.tex Fri Mar 24 23:31:18 2006
@@ -10,152 +10,143 @@
\chapter*{Writing reSTructuredText for documentation and doctests}
\begin{problem}
-translation to finish
+The whole Zope documentation available inside its packages is written in
+reSTructuredText or reST, which is an evolution of StructuredText. This
+structured text is more readable as is than LaTeX, since the tags don't change
+the text itself. Tools allow then to convert reST files to
+publishable formats like HTML, XML or PDF.
-L'ensemble de la documentation des paquets de Zope est r�alis�e au format
-reSTructuredText, ou reST, qui est une �volution du StructuredText. Ce format
-fourni une structure simple, qui n'alourdit pas le texte, contrairement �
-LaTeX, et peut �tre lu directement. Des outils permettent ensuite de manipuler
-ce contenu pour le transformer en HTML, LaTeX, XML ou PDF.
-
-Cette recette est une \textit{cheatsheet} minimale, qui permet d'�crire des
-doctests destin�s � des paquets Zope, une documentation plus compl�te pouvant
-�tre trouv� � cette URL:
+This recipe is a minimal \textit{cheatsheet} to write doctests for Zope
+packages using reST. A complete documentation is available here:
\url{http://docutils.sourceforge.net/rst.html}.
\end{problem}
\begin{solution}
-\section*{Structurer le fichier}
-Pour organiser un fichier en section, sous-section, sous-sous-section, etc.,
-il suffit de souligner le titre de la section avec un caract�re dans
l'ensemble:
+\section*{Structuring the file}
+To organise a file into sections, subsections and so forth, the section title
+just need to be underlined with a character from:
\begin{verbatim}
= - ` : ' " ~ ^ _ * + # < >
\end{verbatim}
-A chaque section, si un nouveau caract�re est utilis�, reST l'associe au niveau
-donn� pour le reste du document.
+Whenever the reST engine meet such underlines, it links the given level to
+the character in use, for the rest of the document.
-\codetitle{Exemple de structure reST:}
+\codetitle{a reST example:}
\begin{verbatim}
-Titre
+Title
=====
-Ok, donc j'ai deux sections. Profitez-en.
+Ok, so I have two sections, enjoy !
Section 1
~~~~~~~~~
-Le titre est un frimeur. j'en parle dans une sous-section.
+The title shows off. I talk about it in a subsection.
-Sous-Section 1
---------------
+Subsection 1
+------------
-Je suis charg� par ma section de casser du sucre sur le dos
-de Titre, mais je n'en ferais rien, je vise une promotion.
+Section 1 asked me to make fun of Title, but I won't, since
+I am trying to get promoted.
Section 2
~~~~~~~~~
-Calmons nous, le document est fini de toute mani�re...
+Let's calm down folks, the document is over...
\end{verbatim}
-\section*{Ins�rer des exemples de code}
+\section*{Inserting code examples}
-Ins�rer du code se fait en l'indentant d'au minimum 1 caract�re (en g�n�ral 2
-ou 4). Ce bloc doit �tre pr�c�d� du signe "::" et d'une ligne vide, puis
-suivi d'une ligne vide.
+Inserting a code bloc is done by indenting it with at least one character.
+(most of the time people do 2 or 4). The bloc must be preceded by a "::" sign
+and an empty line, then forwarded by an empty line.
-\codetitle{Insertion de code:}
+\codetitle{Code insertion:}
\begin{verbatim}
-Le module Math
-==============
+The Math module
+===============
-Python dispose d'un module math, qui fourni une fonction pour les puissances::
+Python has a math module that has a function for power::
>>> import math
>>> math.pow(56, 3)
175616.0
-Il y a aussi pi::
+It has pi as well::
>>> math.pi
3.1415926535897931
-
\end{verbatim}
\begin{codenotes}
-\item Zope 3 indente de deux caract�res, mais certains d�veloppeurs pr�f�rent
-une indentation sur 4 caract�res, peut �tre pour �diter plus facilement
-ces fichiers dans leur �diteur de code Python.
+\item Zope 3 use a 2 spaces identing, but some developers use 4, like
+Python code.
\end{codenotes}
-\section*{Ins�rer des liens et formater le texte}
+\section*{Inserting links and formatting the text}
-\noindent reST permet aussi d'afficher du texte en italique, en gras.
+\noindent reST provide tags to display bold or italic text.
-\codetitle{Gras et italique:}
+\codetitle{Bold and italic:}
\begin{verbatim}
-Recette
-=======
+Facts
+=====
-Il n'y a absolument pas de **gras** dans les plats `italiens`.
+They aren't more **bold** people in `Italia` than in other part of the world.
\end{verbatim}
-\noindent La notation italique est utilis�e pour mettre en exergue un module
-ou tout �l�ment de code dans le texte. La notation grasse est r�serv�e � la
-mise en valeur de mots du texte.
+\noindent Italic is used to emphasis a module name or a inline piece of code.
+Bold is dedicated to regular text emphasis.
-Pour les liens, les deux types les plus courants sont les liens complets
-vers des ressources Web (URL), et les liens vers une autre partie du document.
+For links, the most common types are links to Web resources (URL), and
+kickers to other parts of the current document.
-Les URL peuvent �tre associ�s � un texte mis entre simple c�tes, et suivit
-d'un espace soulign�. Ce texte est ensuite r�p�t� en bas de document, pr�c�d�
-de deux points, un espace , puis un espace soulign�, puis de l'URL pr�c�d�
-du symbole ":".
+Like in HTML, links can be associated to a piece of text, which is quoted,
+followed by an underline. This text is repeated at the bottom of the document,
+preceded by two dots, a space and an underline, then forwarded by the URL,
+with a ":" prefix.
-\codetitle{Exemple d'URL:}
+\codetitle{Link example:}
\begin{verbatim}
-Ordonnance
-==========
+Daily job
+=========
-Matin et soir : un tour sur `zope-cookbook`_
-Midi: Ne pas oublier le suppositoire.
+Morning and evening : a visit to `zope-cookbook`_
+Noon: Don't forget your pill.
.. _`zope-cookbook`: http://zope-cookbook.org
\end{verbatim}
\begin{codenotes}
-\item La r�f�rence en bas de page disparait bien s�r, lorsque le texte est par
-exemple g�n�r� en HTML ou PDF.
+\item The footer reference is removed when the text is rendered in HTML, PDF
+or another publishing format.
\end{codenotes}
-Pour d�finir des liens dans le document m�me, le m�me type de marquage est
-employ�, sauf pour la section cible: la phrase r�p�t�e est suivi uniquement
-de ":".
-
-\codetitle{Exemple de r�f�rences dans le document:}
-\begin{verbatim}
-Ordonnance
-==========
-
-Matin et soir : un tour sur `zope-cookbook`_
-_`suppositoire`:
-Midi: Ne pas oublier le suppositoire.
+To define links within the document itself, the same kind of markup is
+used, but the target is marked with the reference followed by ":".
+
+\codetitle{Links in the documents:}
+\begin{verbatim}
+Daily job
+=========
+
+Morning and evening : a visit to `zope-cookbook`_
+_`pill`:
+Noon: Don't forget your pill.
_`zope-cookbook`:
-Zope-cookbook.org est un site tr�s sympa. Mais avant d'y aller,
-avez vous pens� � votre `suppositoire`_ ?
+Zope-cookbook.org is a neat place, but before you go there,
+don't forget to take your `pill`_.
\end{verbatim}
-\section*{Adopter de bonnes pratiques}
+\section*{Adopting good practices}
-Voici une liste de bonne pratiques en vrac:
+A few good practices, unordered:
\begin{itemize}
-\item V�rifier � ce que le fichier reST soit toujours syntaxiquement valide,
-avec \code{rest2html} par exemple;
-\item regrouper les liens en fin de fichier;
-\item les fichiers reST constituent la documentation du paquet, ils doivent
-�tre particuli�rement soign�s ;
-\item Les en-t�tes de modules, de classes et autres fonctions peuvent aussi
-adopter ce format.
+\item Make sure the reST file always compiles. With \code{rest2html} for
+example;
+\item group link references in the bottom of the document;
+\item reST files are package documentation, they should be well written;
+\item Module, class and method docstrings can use reST as well.
\end{itemize}
\end{solution}
--
http://lists.nuxeo.com/mailman/listinfo/z3lab-checkins
