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
C:\Python26\Scripts>rst2pdf D:\example.rst --language="pl" --output=D:\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
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