plint

French poetry validator
git clone https://a3nm.net/git/plint/
Log | Files | Refs | README

README (5244B)


      1 plint -- a French poetry validator
      2 Copyright (C) 2011-2012 by Antoine Amarilli
      3 
      4 == 0. Licence ==
      5 
      6 This program is free software: you can redistribute it and/or modify it under
      7 the terms of the GNU General Public License as published by the Free Software
      8 Foundation, version 3.
      9 
     10 This program is distributed in the hope that it will be useful, but WITHOUT ANY
     11 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
     12 PARTICULAR PURPOSE.  See the GNU General Public License for more details.
     13 
     14 You should have received a copy of the GNU General Public License along with
     15 this program (see file "COPYING").  If not, see <http://www.gnu.org/licenses/>.
     16 
     17 bottle.py is a third-party file, its license is in file LICENSE_bottle.
     18 
     19 test/boileau and test/andromaque are from Wikisource and test/baudelaire and
     20 test/mithridate are from Project Gutenberg. Both of them are in the public
     21 domain.
     22 
     23 == 1. Features ==
     24 
     25 plint is a tool to check French poetry. Specifically, it validates metric,
     26 rhymes and rhyme genres against an unexpressive template language. It features a
     27 command-line interface, an IRC wrapper (for use with irctk) and a web interface.
     28 It depends on haspirater <https://a3nm.net/git/haspirater> and frhyme
     29 <https://a3nm.net/git/frhyme>, and the web interface requires CherryPy.
     30 
     31 The full documentation of plint's features is available in views/about.html.
     32 
     33 == 2. Getting started ==
     34 
     35 This section provides a quick summary of how to get started with setting up and
     36 using plint. If these instructions do not work for you, please let me know.
     37 
     38 0. Basic setup
     39 
     40 Make sure that you have a working python3 installation and that you have unzip
     41 (Debian packages: python3, unzip).
     42 
     43 1. Clone the plint repository
     44 
     45 If you haven't done so already:
     46 
     47   git clone https://a3nm.net/git/plint/
     48   cd plint
     49 
     50 2. Retrieve the dependencies
     51 
     52 In the directory where plint has been cloned, run:
     53 
     54   git clone https://a3nm.net/git/haspirater/
     55   git clone https://a3nm.net/git/frhyme/
     56 
     57 3. Generate frhyme.json
     58 
     59 Run:
     60 
     61   cd frhyme
     62   lexique/lexique_retrieve.sh > lexique.txt
     63   ./make.sh 4 lexique.txt additions > frhyme.json
     64   cd ..
     65 
     66 4. Link the missing files
     67 
     68 Run:
     69 
     70   ln -s frhyme/frhyme.py
     71   ln -s frhyme/frhyme.json
     72   ln -s haspirater/haspirater.py
     73   ln -s haspirater/haspirater.json
     74 
     75 5. Generate the occurrences file
     76 
     77 Run:
     78 
     79   ./lexique_occurrences_retrieve.sh > occurrences
     80 
     81 6. Locales
     82 
     83 For locale support, install gettext (Debian package: gettext) and run:
     84 
     85   make
     86 
     87 7. Running plint
     88 
     89 If you want to check a poem that consists of classical alexandrines with flat
     90 rhyme (like the file test/mithridate), write the contents of the poem to check
     91 into a file poem.txt. Then run:
     92 
     93   ./plint.py test/mithridate.tpl < poem.txt
     94 
     95 Plint will display the errors (if any) and exit.
     96 
     97 8. Customizing the template
     98 
     99 If you want to customize the template of the poem, you can look at examples on
    100 the online tool (https://plint.a3nm.net/fr/) or files ending in ".tpl" in the
    101 source repository. You can then write your template into a file called
    102 template.tpl and run:
    103 
    104   ./plint.py template.tpl < poem.txt
    105 
    106 The file format for templates is tersely documented on
    107 https://plint.a3nm.net/en/about#template
    108 
    109 == 3. Detailed usage ==
    110 
    111 To use the program's command-line interface, run:
    112 
    113   ./plint.py TEMPLATE
    114 
    115 where TEMPLATE is the template file, and provide the poem on stdin. Errors are
    116 reported on stderr.
    117 
    118 To run the web interface on port 5000, run plint_web.py. CherryPy is required
    119 (but the code is easy to adapt), see
    120 http://bottlepy.org/docs/dev/tutorial.html#deployment
    121 Beware, if you use CherryPy under Debian, simply installing python-cherrypy3
    122 might not work ("no module named cherrypy"). In this case, you need to install
    123 CherryPy by hand from source (sudo python3 setup.py install).
    124 
    125 An undocumented IRC interface for use with irctk is available (plint_irc.py).
    126 The poem that it produces can be compiled to HTML automatically using something
    127 along the lines of:
    128 
    129   while true
    130   do
    131     inotifywait poem_file
    132     # www/ should contain style.css
    133     poem2html/make_poem.sh poem_file > www/poem.html
    134   done
    135 
    136 To run plint on some provided test files, you can use test.sh. However, because
    137 of known bugs, some errors will be reported on the test files. To run a very
    138 simple test suite, run ./versetest.py; they should all pass.
    139 
    140 == 4. Training ==
    141 
    142 The diaeresis pattern "diaeresis.json" is trained by calling
    143 
    144   ./train_diaeresis.sh > diaeresis.json
    145 
    146 You can also train a specific pattern for _Cyrano de Bergerac_ with:
    147 
    148   ./train_diaeresis.sh _full ../additions_cyrano > diaeresis_cyrano.json
    149 
    150 This is currently undocumented. The plint folder should contain a copy of the
    151 haspirater code (possibly as a symlink) in "haspirater/".
    152 
    153 == 5. Related work ==
    154 
    155 * http://pentametron.com/
    156 * http://virga.org/cvf/alexanql.php
    157 * http://hal.archives-ouvertes.fr/docs/00/37/73/48/PDF/1.Rythme_et_rime_de_l_alexandrin_classique_-_V_Beaudouin_2000.pdf
    158 * http://www.oulipo.net/docannexe/file/16251/MetreenregleRFLA-Beaudouin200405.pdf
    159 * http://images.math.cnrs.fr/Je-demeurai-longtemps-errant-dans.html
    160 * Beaudouin V. & Yvon F. (1996). "The Metrometer : a Tool for Analysing French Verse", Literary & Linguistic Computing, vol. 11, n°1, p. 23-32.
    161 * http://corpus.revues.org/290
    162