reStructuredText

Zainspirowany dyskusją z blogerem Orlando postanowiłem przyjrzeć się bliżej językowi znaczników reStructuredText, będącego komponentem systemu Docutils, wykorzystywanego m.in. przez generator dokumentacji Sphinx. Dyskusja dotyczyła modułu rst2odp, który umożliwia konwersję pliku rst do pliku prezentacji multimedialnej odp, którą można otworzyć w OpenOffice lub MS Office.

Ten wpis będzie się składał z dwóch części. Pierwsza dotyczyć będzie jednego ze sposobów instalacji pakietów dla języka Python, a druga konwersji plików rst na inne formaty.

INSTALACJA PAKIETÓW

Instalacja dodatkowych modułów dla języka Python może odbywać się na kilka sposobów:

1. Kompilacja ze źródeł 2. Instalacja pakietów binarnych (np. z repozytorium dystrybucji Linuksowych) 3. Instalacja odpowiednio przygotowanych dla systemu Windows plików exe 4. Instalacja przy pomocy narzędzia easy_install

Tym razem wykorzystamy narzędzie easy_install. Zasada działania easy_install przypomina np. znany z Ubuntu system zarządzania pakietami APT. Sposób instalacji pakietów przy pomocy easy_install zostanie omówiony na przykładzie Windowsa, choć w systemach klasy Unix odbywa się to bardzo podobnie.

Aby móc skorzystać z easy_install należy zainstalować pakiet setuptools.

Po zainstalowaniu uruchamiamy wiersz poleceń, przechodzimy do katalogu Scripts

cd C:\Python26\Scripts

i przy pomocy narzędzia easy_install instalujemy pozostałe wymagane w dalszej części opisu moduły:

easy_install docutils
easy_install Pygments
easy_install PIL

Następnie instalujemy moduły do konwersji plików rst na wybrany format wyjściowy

easy_install rst2pdf
easy_install rst2beamer
easy_install rst2odp

rst2pdf umożliwia konwersję pliku rst do PDF‑a, rst2beamer do pliku tex, a rst2odp do pliku prezentacji OpenDocument.

Dygresja:

Plik tex uzyskany przy pomocy rst2beamer jest plikiem prezentacji w systemie LaTeX z klasą Beamer. Patrz: dobraprezentacja. PIL (Python Imaging Library) jest biblioteką do zaawansowanej obsługi obrazów dla języka Python. Patrz: Styl retro.

Lista paczek dla Pythona znajduje się na stronie PyPi.

KONWERSJA RST DO WYBRANEGO FORMATU WYJŚCIOWEGO

Po zainstalowaniu powyższych pakietów mamy możliwość skorzystania z kilku narzędzi do konwersji plików reStructuredText na wybrany format plików wyjściowych, np.: html, tex, pdf, odt, odp.

reStructuredText charakteryzuje się bardzo prostą i czytelną składnią. Mimo, że przy tworzeniu dokumentu posługujemy się "zwykłym tekstem", dokumenty tworzone są zgodnie z zasadą what-you-see-is-what-you-get, a nie tak jak w przypadku np. LaTeX-a what-you-see-is-what-you-mean. Dzięki temu możemy w prosty i przyjemny sposób otrzymać ładnie sformatowane pliki PDF, html itd.

Ze składnią reStructuredText można zapoznać się na stronie quickref. Efekt działania można obserwować korzystając z renderera online reST.

Krótki opis w języku polskim oraz przykłady znajdziemy na stronie cs.put.poznan.pl.

Zawartość strony z przykładem first.txt zapisujemy w pliku example.rst np. na dysku D. Do tego celu tradycyjnie polecam edytor gVim, który świetnie radzi sobie z kolorowaniem składni. Można oczywiście skorzystać z dowolnego edytora / notatnika.

Ciekawym edytorem dostępnym dla systemu Windows i Linux jest reStructuredText Editor.

Można także skorzystać z edytora online zapewniającego podgląd w czasie rzeczywistym.

Uruchamiamy wiersz polecenia (cmd) i przechodzimy do katalogu Scripts

cd C:\Python26\Scripts

Aby uzyskać pomoc na temat wybranego konwertera używamy opcji -‑help, np.

rst2pdf --help

Skonwertujmy zatem zapisany na dysku D plik example.rst do różnych plików wyjściowych.

HTML

C:\Python26\Scripts>rst2html.py D:\example.rst D:\example.html

example.html

PDF

C:\Python26\Scripts>rst2pdf D:\example.rst --language="pl" --output=D:\example.pdf

example.pdf

LaTeX

C:\Python26\Scripts>rst2latex.py --output-encoding=cp1250 D:\example.rst D:\example_tex.tex

gdzie

--output-encoding=cp1250

jest stroną kodową używaną przez system Microsoft Windows do reprezentacji tekstów w językach środkowoeuropejskich.

example_tex.tex, po skompilowaniu w LaTeX-u otrzymujemy example_tex.pdf

LaTeX Beamer

C:\Python26\Scripts>rst2beamer --output-encoding=cp1250 D:\example.rst D:\example_beamer.tex

W ten sposób otrzymujemy gotowy plik tex z prezentacją, do którego możemy dodać szczegóły w postaci tytułu, autora itd. oraz zmodyfikować temat graficzny itp. Opcje te można też dodać jako parametry przy kompilacji. Patrz: rst2beamer -‑help

example_beamer.tex, po skompilowaniu w LaTeX-u otrzymujemy example_beamer.pdf

ODT

C:\Python26\Scripts>rst2odt.py D:\example.rst D:\example.odt

example.odt

ODP

C:\Python26\Scripts>C:\Python26\python.exe rst2odp D:\example.rst D:\example.odp

niestety kończy się komunikatem o błędzie

WindowsError: [Error 32] Proces nie mo¬e uzyskaŠ dostŕpu do pliku, poniewa¬ jest
 on u¬ywany przez inny proces: 'c:\\users\\krystian\\appdata\\local\\temp\\tmpuw5sks'
Exiting due to error.  Use "--traceback" to diagnose.
Please report errors to .
Include "--traceback" output, Docutils version (0.7 [release]),
Python version (2.6.6), your OS type & version, and the
command line used.

Zobacz również: Prezentacja wideo na temat reStructuredText