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