Escriure documentació és una tasca complexa i si no disposam de un bon control damunt el format que empram per escriure ens podem trobar sovint amb tasques de copiar i aferrar entre distints editors. Hi ha una alternativa: escriure text pla i després generar automàticament la documentació en distints formats. Si aquest text pla és directament legible i les marques són entenidores doncs ja ho tenim tot. El reStructuredText compleix tot això.
Per cert:
Traducción automática aquí via Internostrum
reStructuredText, el WYSIWYG en text pla
Què
és el reStructuredText?
En la seva concepció inicial el reStructuredText es
va pensar com un llenguatge de marques que s’integràs amb
els programes Python, de manera que a partir dels comentaris del codi
es pogués generar la documentació.
En aquests moments, però reStructuredText ha
evolucionat cap a un llenguate de marques prou senzill per a tothom ho
pugui fer anar sense pràcticament esforç
d’aprenentatge, i el que és més important, en un
llenguatge de marques que converteix el text pla en un WYSIWYG (What
You See Is What You Get).
A diferència amb altres llenguatges de marques, com
l’HTML, o LaTeX, un document en reStructuredText es veu
bé i és llegeix
bé des del propi codi, no fa falta un pas
addicional ni visor especial, qualsevol editor que pugui llegir text
pla i no faci servir fonts proporcionals [1] pot ser utilitzat per editar i
visualitzar un document en aquest format. A més,
però, pot genera documentació de qualitat en
Latex, pdf o HTML entre d’altres formats.
reStructuredText és la feina de David Goodger i del
grup de desenvolupament i usuaris de Python que l’han anat enriquint
amb les seves aportacions. Des d’aquí el meu
agraïment sincer.
[1]Qualsevol
serviria, de fet, però si ja directament no fa servir fonts
proporcionals ens estalviem la feina de canviar de font.
Per què
fer servir resTructuredText
Molt bé, ja l’hem presentat. Ara molts potser us
demanareu perquè l’hem de fer servir si amb l’HTM o el LaTeX
o el nostre processador de text ja anam fet. Per mi el
reStrucutredText té un gran avantatge damunt un format tipus
OpenDocument i és que ho puc llegir i imprimir amb facilitat
sense haver d’obrir cap visor i el text conserva el format
bàsic necessari com per ser entenidor.
El reStructuredText està molt més a prop
de la sintaxi d’un Wiki que de cap altra cosa, però ha anat
un pas més enllà i ha fet que el propi document
es pugui llegir fàcilement, i ha fet que les marques de
format necessàries per donar vistositat al document siguin
d’allò més naturals.
Com a programador l’avantatge fonamental que té per
mi, però, és que com és text pla ho
puc posar fàcilment dins un control de versions i fer servir
el mateix editor que faig servir per programar (el Vim, Kate o
l’Eclipse), no he de canviar d’editor per fer la
documentació tècnica [2] o d’anàlis del programa
i és més, aquesta documentació pot
estar directament dins el mateix control de versions que el codi.
Aquest control de versions permet, si se dona el cas, que
més d’una persona estigui fent feina amb el document sense
gaires problemes i sense imposar-los cap editor en concret.
Des d’una altre punt de vista, el de la protecció
de la inversió i de la perdurabilitat
de la feina feta, reStructuredText en no dependre de cap visor
especial, ens garantitza que la nostra feina serà visible
independentment de les versions que processador de text que es facin.
Mentre existesqui quelcom capaç de fer un llistat d’un arxiu
de text podrem llegir la nostra feina [3]
Per la meva part, vaig arribar al reStructuredText quan
cercava alguna manera de poder posar la documentació sota el
control de versions. Estic força acostumat a fer anar el
LaTeX [4], però
posar totes les marques de LaTeX implicava que per a llegir el document
s’havia de passar a un altre format quan el text ho havia de llegir
gent poc acostumada a LaTeX.
Estava provant la sintaxi dels Wikis quan vaig
començar a jugar amb un projecte anomenat Django
i vaig quedar soprés per la qualitat de la seva
documentació. Quan vaig agafar el projecte del respositori
de subversions del projecte, vaig veure que junt amb el codi Python
venia també un bon conjunt d’arxius de text amb la
documentació, que per la meva sorpresa es podia imprimir i
quedava fantàsticament bé. Era just el que
necessitava pels meus propis projectes!
Configuració
El format es tan simple que no necessita
instal·lació. Sols ganes d’escriure i llegir-se
el manuals d’introdució. 🙂
Però bé, com que segurament el que
voldreu després és treure el document en pdf o
html convé instal·lar el paquet python-docutils
de la vostra distribució preferida. Si teniu el Python
instal·lat al vostre ordinador segurament ja ho tindreu
instal·lat. Aquest paquet conté el parser de
reStructuredText de manera que fent:
rst2html <origen.rst> <desti.html>
ja
tendrem el nostre text pla passat a html o fent
rst2latex <origen.rst> <desti.tex>
ho
podem passar a format LaTeX.
Si voleu també podem fer des de la línea
de comandaments:
rst2newlatex.py article.rst article2.tex ;
pdflatex article2.tex ; evince article2.pdf
i
ja teniu aquest fitxer convertit a pdf i visualitzat 🙂
[2]Fer
servir un mateix editor per totes les tasques és una
recomanació que ens fan Andrew Hunt i David Thomas al
Pragmatic Programmer, com una manera de ser més productius.
[3]En
la línea del que diu Neil Stephenson a “En el principio fue
la línea de comandos” que podeu trobar en la
versió castellana a http://www.sindominio.net/biblioweb/telematica/command_es/
[4]Vegeu
el meu petit manual a http://bulma.net/body.phtml?nIdNoticia=1874
Utilització
Podem trobar una referència ràpida a Quick
reStructuredText i una guia encara més
ràpida a A
ReStructuredText Primer i a les Referències
trobareu més enllaços cap a
documentació.
Una bona guia d’aprenentatge és aquest document o
qualsevol dels documents que s’han creat amb reStructuredTex. Una de
les millors documentacions que he vist són les de Django,
així que us aconsell que si us interessa el tema us baixeu
tant aquest manualet com el de Django i
vegeu com està fet.
El que ara us presentarè és una petita
guia per fer l’entrada a reStructuredText més
ràpida, donant-vos les indicacions per fer servir
reStructuredText per crear documentació.
Començant
a escriure
El primer que hom fa quan escriu un document és
posar-ne el títol. En el cas d’aquest article el
títol s’escriu::
=========================================
reStructuredText, el WYSIWYG en text pla
=========================================
Com
podeu veure queda molt clar que és un tilular [5]. Després seguim amb les
seccions i subseccions. Això també és
molt clar, ja que basta subratllar el text de la secció o
subsecció amb igual, o guionets. Heu de subratllar al manco
la longitud de la frase. Així
Això és una secció
===================
Això és una subsecció
———————-
El
subratllat convé que indiqui la importància de la
secció. Així a mi m’agrada més
utilitzar iguals per seccions i guionets per les subseccions.
Ara que ja tenim clara l’estructura bàsica del
text començarem a escriure els nostres primers
paràgrefs de text. Per reStructuredText un paràgref
és un bloc de text separat per dues línees en
blanc on totes les línees comparteixen el mateix nivell
d’identació. És a dir, que comencen a la mateixa
columna.
Estils
del text
També ens insteressarà segurament
resaltar alguna frase o paraula. Això ho podem fer emprant
la lletra negreta o la cursiva. La negreta s’aconsegueix posant dos
arteriscs * a l’inici i al final del text que volem resaltar, la
cursiva s’aconsegueix posant-ne tant sols un. Així:
Si posam **negreta** tendrem negreta
i si posam *cursiva* tendrem cursiva
Com que hi haurà vegades en que le que ens
interessarà és escriure un arterisc i no volem
que s’interpreti com a una cursiva o una negreta, haurem de fer serir
la barra descendent \ per escapar el significat
de l’arterisc. Si el que volem és posar una barra
també l’haurem d’escapar i per tant
l’escriurem com a \\
Listes
Tenim a la nostra disposició un bon conjunt d’eines
per fer llistes:
Llistes
numerades
Per escriure una llista
numerada basta començar la nostra frase amb un
símbol d’enumeració típic, per
exemple, un número i un punt, una lletra i un punt, un
número o lletra seguit d’un parèntesi o entre
parèntesi.
Per autonumerar la llista podem escriure el #.
Així les llistes anteriors s’han escrit així:
1. un
2. dos
a. un
b. dos
#. això és automàtic
Per
a que el text formi part de la llista ha d’estar identat. Per a
aconseguir
un Li Europan lingues es membres del sam familie.
Lor separat existentie es un myth. Por scientie, musica, sport etc., li
tot Europa usa li sam vocabularium.
S’ha d’escriure:
1. un
2. Li Europan lingues es membres del sam familie.
Lor separat existentie es un myth. Por scientie, musica, sport etc.,
li tot Europa usa li sam vocabularium.
Llistes no numerades
Una llista no numerada
és semblat a la numerada en quant a utilització o
sintaxi, sols que ara farem servir com a símbol d’inici de
la llista en guionet -, l’arterisc * o el signe més +
- Lista no numerada
- Llista numerada
- Definició
- Etc
S’ha escrit:
* Lista no numerada
* Llista numerada
* Definició
* Etc
Definicions
Per escriure una
definició basta escriure una frase, la definició,
i el paràgref que conté la definició
identat respecte a la frase a definir, sense cap línea en
blanc de separació.:
Friki
Es diu de la majoria que llegim aquestes coses,
i que a més les feim servir.
Prou senzill i estructurat, no?
Llistes de camps
Les llistes de camps ens
proporcionen una manera fàcil i ràpida de crear
dues columnes als nostres documents. També són
ideals per escriure informació bibliogràfica, les
capçaleres de la documentació,etc. Per exemple:
:Autor:
Antoni Aloy
aaloy(at)bulma.net
:Data:
Abril-2006
:Agraïments:
David Goodger pel reStructuredText
Dóna
com a resultat:
Autor:Antoni Aloy
aaloy(at)bulma.net
Data:Abril-2006
Agraïments:David
Goodger pel reStructuredText
Llistes d’opcions
Les llistes d’opcions serveixen
per documentar paràmetres de línea de
comandaments, tant a l’estil clàssic de Unix, amb guionet
simple, com amb doble guionet o a l’estil de DOS/VMS. Per a que
s’interpreti com a una llista d’opcions hi ha d’haver al manco dos
espais de separació entre l’opció i la seva
documentació.
-h
Mostra aquesta ajuda i surt
–help
Mostra aquesta ajuda i surt.
–version
Mostra informació sobre la versió i
surt.
/h
Ajuda
S’ha escrit
-h Mostra aquesta ajuda i surt
–help Mostra aquesta ajuda i surt.
–version Mostra informació sobre la versió i surt.
/h Ajuda
Si el que hem fet fins ara us ha agradat, el
que ve ara us deixarà encara més
convençuts del que arriben a ser de legibles els documents
en reStructuredText. I és que les taules són el
maldecapt de molts llenguatges de marques, l’html, el wiki, LaTex no
se’n lliuren de la complexitat de lectura i escriptura de taules, i en
el cas dels wikis fa que perdin gran part de la seva gràcia
com a llenguatges de marques simples. Vegem amb un exmple com ho ha
rsolt reStructuredText. Escriure:
=== =====
x y=x+1
=== =====
0 1
1 2
-1 1
=== =====
Ens
dóna la taulax
y=x+10
1
1
2
-1
1Si volem fer coses més complexes
podem fer servir una estructura de taula més rica, on es fan
servir signes més (+) per les arestes, el símbol
| per pintar les línees verticals i iguals (=) i guionets
(-) per pintar les línees horitzontals. El criteri
és sempre que la taula quedi legible en format text.TITULAR
TITULAR 2abc
cel·la
cel.la 2
asldfsadfaasd adsf
asdfasd
ha quedat
prou bé
no trobau?Els amants de l’ASCII Art
es trobaran com a casa amb aquesta representació de les
taules.:
+———–+————-+————+
| TITULAR | TITULAR 2 |
+===========+=============+============+
| abc | cel·la | cel.la 2 |
+———–+————-+————+
| asldfsadfaasd adsf | asdfasd |
+———–+————-+————+
|ha quedat |prou bé | no trobau? |
+———–+————-+————+
Aquí
ens hem de fixar en com els signés més ens
defineixen les columnes i com l’absència del separador
vertical afegeix dues cel·les. Una vegada s’ha vist fer una
taula resulta molt intuïtiu.
En el món de l’hipertext
és fonamental poder posar enllaços, en el
món de la documentació les referències
i els peus de pàgines no són menys importants.
En aquest document he fet ús i abús dels peus de
pàgina i enllaços, així que anem a
veure com es posen.
Una nota a peu de pàgina es fa amb [x]_
on la x representa un nombre. Després sols cal escriure la
nota a una línea nova començant per dos punts i [x]
sense el guionet aquesta vegada. Per exemple::
Li Europan lingues [1]_ es membres del sam familie.
Lor separat existentie es un myth. Por scientie, musica, sport etc.,
li tot Europa usa li sam vocabularium. Li lingues differe solmen in
li grammatica, li pronunciation e li plu commun vocabules.
Omnicos directe al desirabilitá de un nov lingua franca:..[1] El generador de Firefox pel Lorem Ipsum va força bé.
Dins
aquest document trobareu força exempleis de com queda. Com
que recordar per quina nota anam pot no ser fàcil en un
document extens, bastaria posar en el lloc del nombre el signe # i
automàticament en generar el document final s’autonumeraran
les notes a peu de pàgina, però això
té l’inconvenient que el document en text pla no queda tan
clar.
Els enllaços interns es posen amb criteris
semblants, és a dir, per fer referència a un
enllaç intern posarem un signe de subrallat al final de la
paraula, en el cas de que l’enllaç sigui una frase aquesta
haurà d’estar entre accents greus. Per defecte tenim ja
definides les seccions com a referències internes d’un
document, per la qual cosa si posam per exemple Utilització_
dins aquest document ens durà a Utilització. Els
incrèduls podeu fer clic a l’enllaç anterior!
Podem posar marques dins el nostre document per fer-ne
referència més tard. Aquestes marques es posen
amb dos punts, un espai, el nom de la marca i dos punts. Per exemple he
creat una referència .. _taules al
començament de la documentació referent a com fer
taules en reStructuredText, si ara hi volem anar: taules.
La manera de definir hiperenllaços és
molt senzilla, el guionet es posa al davant per la definició
i al darrera a l’hora de fer servir l’enllaç. Per
enllaços externs la cosa no canvia gaire, sols que
deprés dels dos punts hi hem de posar la URL de
l’enllaç, per exemple escriurem Bulma_
allà on volguem enllaçar i després ..
_Bulma: http://www.bulma.net a una altra línea.
I la cosa queda com: Bulma. Si volem
definir la url al mateix temps que la utilitzam podem escriure-la
directament http://www.trespams.com,
o si volem ser una mica més fins `La meva pàgina
<http://www.trespams.com/>`_
que crearia La meva pàgina.
Particularment m’agrada més definir els enllaços
apart i per tant no recomanaria la darrera opció.
Les cites bibliogràfiques es defineixen i
s’utilitzen de manera semblant. Per exemple [PRPRG]_ queda com [PRPRG]
[PRPRG]The
Pragmatic Programmer 16th Edition July 2005. Addison-Wesley. Andrew
Hunt & David Thomas.
[5]Per
aquells que com jo ja teniu una edat, segur que us recordarà
els títols que posaveu amb la màquina d’escriure.
reStructuredText se pareix molt a escriure documentació amb
una màquina d’escriure mecànica, sols que
després la sortida que podem tenir si ho passam per un
filtre LaTeX o HTML és molt més rica.
Imatges.
Essent text pla, posar imatges no queda massa bé
si hom vol llegir el document directament, però si el que
volem fer és passar-ho a html o pdf, el reStructuredText ens
permetrà posar-ne.
El logo de Bulma, per exemple:
S’ha
inserit amb .. image:: bulma_small.jpg
Conclusions
Si heu aconseguit arribar aquí l’enhorabona, ja
sabeu què és el reStructuredText i segurament
podreu fer-ho servir sense problemes en els vostres projectes.
Segurament us estalviarà molts de mal de caps,
després de tot heu aconseguit tenir el control total damunt
el vostres texts i tenir la capacitat dd’escriure amb qualsevol editor
i que el que heu escrit sigui directament legible.
El reStructuredText no acaba aquí, hi ha
més coses, més opcions, podeu personalitzar
l’estil de sortida, no deixeu de veure les Referències
Per acabar he deixat una sèrie
d’enllaços que esper siguin d’utilitat:
- El text original
d’aquest document - El text en html, en UTF-8
- El text en pdf
- El text en format LaTex
- I perquè no, en XML
- Història
del reStructuredText. Perquè sempre es bó saber
d’on venim. - Pàgina
principal de reStructuredText. La majoria
d’enllaços que he citat surten d’aquesta pàgina. - Resaltat de
sintaxis per Vim. Es per les darreres versions de Vim, encara
que no ho pogueu fer servir conté un manual molt clar de la
sintaxi de reStructuredText. - Un
altre resaltador de sintaxi - Presentacions
amb reStructuredText
Este post ha sido traido de forma automatica desde https://web.archive.org/web/20140625063149/http:/bulma.net/body.phtml?nIdNoticia=2291 por un robot nigromante, si crees que puede mejorarse, por favor, contactanos.