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