Author: tziade
Date: Thu Mar 23 01:22:22 2006
New Revision: 2697
Modified:
cookbook/trunk/recipe48.en.tex
Log:
savepoint
Modified: cookbook/trunk/recipe48.en.tex
==============================================================================
--- cookbook/trunk/recipe48.en.tex (original)
+++ cookbook/trunk/recipe48.en.tex Thu Mar 23 01:22:22 2006
@@ -3,17 +3,160 @@
\include{macros}
\status{draft}
\author{Tarek Ziad�}
+\translator{Tarek Ziad�}
\begin{document}
\chapter*{Writing reSTructuredText for documentation and doctests}
\begin{problem}
-Not translated in english yet.
+translation to finish
+
+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:
+\url{http://docutils.sourceforge.net/rst.html}.
\end{problem}
\begin{solution}
-Not translated in english yet.
+\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:
+\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.
+
+\codetitle{Exemple de structure reST:}
+\begin{verbatim}
+Titre
+=====
+
+Ok, donc j'ai deux sections. Profitez-en.
+
+Section 1
+~~~~~~~~~
+
+Le titre est un frimeur. j'en parle dans une sous-section.
+
+Sous-Section 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 2
+~~~~~~~~~
+
+Calmons nous, le document est fini de toute mani�re...
+\end{verbatim}
+
+\section*{Ins�rer des exemples de code}
+
+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.
+
+\codetitle{Insertion de code:}
+\begin{verbatim}
+Le module Math
+==============
+
+Python dispose d'un module math, qui fourni une fonction pour les puissances::
+
+ >>> import math
+ >>> math.pow(56, 3)
+ 175616.0
+
+Il y a aussi pi::
+
+ >>> 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.
+\end{codenotes}
+
+\section*{Ins�rer des liens et formater le texte}
+
+\noindent reST permet aussi d'afficher du texte en italique, en gras.
+
+\codetitle{Gras et italique:}
+\begin{verbatim}
+Recette
+=======
+
+Il n'y a absolument pas de **gras** dans les plats `italiens`.
+\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.
+
+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.
+
+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 ":".
+
+\codetitle{Exemple d'URL:}
+\begin{verbatim}
+Ordonnance
+==========
+
+Matin et soir : un tour sur `zope-cookbook`_
+Midi: Ne pas oublier le suppositoire.
+
+.. _`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.
+\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.
+
+_`zope-cookbook`:
+Zope-cookbook.org est un site tr�s sympa. Mais avant d'y aller,
+avez vous pens� � votre `suppositoire`_ ?
+\end{verbatim}
+
+\section*{Adopter de bonnes pratiques}
+
+Voici une liste de bonne pratiques en vrac:
+\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.
+\end{itemize}
\end{solution}
\end{document}
--
http://lists.nuxeo.com/mailman/listinfo/z3lab-checkins
