plint

French poetry validator (local mirror of https://gitlab.com/a3nm/plint)
git clone https://a3nm.net/git/plint/
Log | Files | Refs | README

README (5687B)


      1 plint -- a French poetry validator
      2 Repository URL: https://gitlab.com/a3nm/plint
      3 Online version: https://plint.a3nm.net/
      4 Python package name: plint
      5 
      6 == 0. Author and licence ==
      7 
      8 plint is copyright (C) 2011-2019 by Antoine Amarilli
      9 
     10 This program is free software: you can redistribute it and/or modify it under
     11 the terms of the GNU General Public License as published by the Free Software
     12 Foundation, version 3.
     13 
     14 This program is distributed in the hope that it will be useful, but WITHOUT ANY
     15 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
     16 PARTICULAR PURPOSE.  See the GNU General Public License for more details.
     17 
     18 You should have received a copy of the GNU General Public License along with
     19 this program (see file "COPYING").  If not, see <http://www.gnu.org/licenses/>.
     20 
     21 The file "plint/data/occurrences" is a derivative work of the French lexical
     22 database Lexique <http://www.lexique.org/>, version 3.83, by Boris New
     23 <http://psycho-usmb.fr/boris.new/> and Christophe Pallier
     24 <http://www.pallier.org/>. Hence, this file is under the same license as
     25 Lexique, namely, the license CC BY SA 4.0 (according to the file
     26 README-Lexique.txt in the downloadable archive of Lexique). The GNP GPL licence
     27 does *not* apply to this file "plint/data/occurrences".
     28 
     29 The files in plint/test_data are public domain works used to test and train
     30 plint. Their sources are given in the file "SOURCES".
     31 
     32 Many thanks to Julien Romero for contributing to the code and for maintaining
     33 the PyPI package for plint and its dependencies.
     34 
     35 == 1. Features ==
     36 
     37 plint is a tool to check French poetry. Specifically, it validates metric,
     38 rhymes and rhyme genres against an unexpressive template language. It has a
     39 command-line interface.
     40 It depends on haspirater <https://gitlab.com/a3nm/haspirater> and frhyme
     41 <https://gitlab.com/a3nm/frhyme>.
     42 
     43 There is also a Web interface for plint in
     44 <https://gitlab.com/a3nm/plint_website>, available online on
     45 https://plint.a3nm.net/. The full documentation of plint's features is available
     46 in views/about.html of that repository, or on https://plint.a3nm.net/en/about.
     47 There is also a repository of bonus content for plint in
     48 https://a3nm.net/git/plint_extra.
     49 
     50 == 2. Getting started ==
     51 
     52 This section provides a quick summary of how to get started with setting up and
     53 using plint. If these instructions do not work for you, please let me know.
     54 
     55 Plint has been packaged for Python and can now be installed by running 
     56 "pip3 install plint". These instructions explain how to install it manually.
     57 
     58 0. Basic setup
     59 
     60 Make sure that you have a working python3 installation and that you have unzip
     61 (Debian packages: python3, unzip).
     62 
     63 1. Clone the plint repository
     64 
     65 If you haven't done so already:
     66 
     67   git clone https://gitlab.com/a3nm/plint.git
     68   cd plint
     69 
     70 2. Retrieve the dependencies
     71 
     72 In the directory where plint has been cloned, run:
     73 
     74   git clone https://gitlab.com/a3nm/frhyme.git
     75   git clone https://gitlab.com/a3nm/haspirater.git
     76 
     77 3. Locales
     78 
     79 For locale support, install gettext (Debian package: gettext) and run:
     80 
     81   make
     82 
     83 4. Running plint
     84 
     85 If you want to check a poem that consists of classical alexandrines with flat
     86 rhyme (like the file test/mithridate), write the contents of the poem to check
     87 into a file poem.txt. Then run:
     88 
     89   python3 -m plint plint/test_data/mithridate.tpl < poem.txt
     90 
     91 Plint will display the errors (if any) and exit.
     92 
     93 5. Customizing the template
     94 
     95 If you want to customize the template of the poem, you can look at examples on
     96 the online tool (https://plint.a3nm.net/fr/) or files ending in ".tpl" in the
     97 source repository. You can then write your template into a file called
     98 template.tpl and run:
     99 
    100   python3 -m plint template.tpl < poem.txt
    101 
    102 The file format for templates is tersely documented on
    103 https://plint.a3nm.net/en/about#template
    104 
    105 == 3. Detailed usage ==
    106 
    107 To use the program's command-line interface, run:
    108 
    109   python3 -m plint TEMPLATE
    110 
    111 where TEMPLATE is the template file, and provide the poem on stdin. Errors are
    112 reported on stderr.
    113 
    114 To run plint on some provided test files, you can use test.sh, which will test
    115 that the errors reported by plint on the input are the "right" ones.
    116 
    117 == 4. Training ==
    118 
    119 The diaeresis pattern "diaeresis.json" is trained by first cloning
    120 haspirater in the main repository folder:
    121 
    122   git clone https://gitlab.com/a3nm/haspirater
    123 
    124 and then calling:
    125 
    126   ./train_diaeresis/train_diaeresis.sh > plint/data/diaeresis.json
    127 
    128 You can also train a specific pattern for _Cyrano de Bergerac_ with:
    129 
    130   ./train_diaeresis/train_diaeresis.sh _full ./train_diaeresis/additions_cyrano > plint/data/diaeresis_cyrano.json
    131 
    132 This is currently undocumented. The plint folder should contain a copy of the
    133 haspirater code (possibly as a symlink) in "haspirater/".
    134 
    135 == 5. Occurrences file ==
    136 
    137 This is how the file plint/data/occurrences is generated
    138 
    139 Run:
    140 
    141   ./prepare_occurrences/lexique_occurrences_retrieve.sh > plint/data/occurrences
    142 
    143 
    144 == 6. Updating the localization ==
    145 
    146 When the code is changed, to update the localization information to French, do:
    147 
    148   cd plint
    149   pygettext *.py 
    150   msgmerge -U res/messages_fr.po messages.pot
    151   poedit res/messages_fr.po
    152   cd ..
    153   make
    154 
    155 == 7. Related work ==
    156 
    157 * http://pentametron.com/
    158 * http://virga.org/cvf/alexanql.php
    159 * http://hal.archives-ouvertes.fr/docs/00/37/73/48/PDF/1.Rythme_et_rime_de_l_alexandrin_classique_-_V_Beaudouin_2000.pdf
    160 * http://www.oulipo.net/docannexe/file/16251/MetreenregleRFLA-Beaudouin200405.pdf
    161 * http://images.math.cnrs.fr/Je-demeurai-longtemps-errant-dans.html
    162 * Beaudouin V. & Yvon F. (1996). "The Metrometer : a Tool for Analysing French Verse", Literary & Linguistic Computing, vol. 11, n°1, p. 23-32.
    163 * http://corpus.revues.org/290
    164