README.md (6220B)
1 # Playfair Script Formatter 2 3 The code for Playfair can be run locally on any machine running Prolog. It is written to be compliant with the ISO standard so your choice of interpreter shouldn't matter. Prolog does all the grunt-work of parsing and formatting the play as HTML. You can then use a converter such as [wkhtmltopdf](https://wkhtmltopdf.org/) to convert the HTML output into a PDF file. 4 5 ## What is the Playfair Script Formatter? 6 7 Writers have a colossal plague in the form of scripts. When you're writing a script you don't want to have to think about how every line is going to be formatted — and yet that's exactly what you have to do. Characters' names have to be indented, dialogue is left-aligned, stage and character directions are italicized and indented at different levels — the list is endless. I have spent hours trying to format my scripts correctly, and I certainly don't want to interrupt my writing by having to click 100 different buttons on the word processor. 8 9 And yet the structure of a script is essentially predictable. The text is delineated in neat blocks that conform to regular patterns. Why not just write the play in plain, unformatted text and run it through a program to format it automatically? That is what the Playfair Script Formatter is for. 10 11 ## How to Use Playfair 12 13 Because Playfair expects a predictable document structure, you have to stick pretty closely to what's expected. To help out, here's a quick demo of features and a checklist of things to do before processing your document. If you don't follow this example, your script will not pass through the formatter correctly. 14 15 ### Sample 16 17 First up, here's a little demo of what a typical script might look like: 18 19 @title: Time Passes Like a Gym Teacher's Laxative 20 @author: Karp, St John 21 22 ACT I Scene 1 23 24 The stage is decorated in the manner of the Belgian Walloons. A Victrola stands in the background. A second-hand car salesman and a priest are onstage. 25 26 The Victrola is playing "Yes! We Have No Bananas". The PRIEST is pacing up and down while the SALESMAN attempts to put toothpaste back into the tube. 27 28 PRIEST 29 (complaining) 30 I find this entire state of affairs unsatisfactory. Don't you realize that unless we can assassinate King Pumpernickel V, the Duke is going to corner the market in rubber chickens? 31 (turning to the salesman) 32 How can you sit there playing with your tube?! 33 34 The SALESMAN looks up. 35 36 SALESMAN 37 It's extra-minty. (indicating the toothpaste) Look, it has stripes. What's the matter, don't you *care* about stripes? 38 39 … 40 41 The End. 42 43 ### The Breakdown 44 45 Let's step through this thing one at a time. You'll notice that each discrete group of text is separated either by a single new line or a double new line. This is very important, as it helps distinguish a character and their dialogue from the next character. Don't go adding extra new lines or you'll wind up with chaos. 46 47 First up, you give your script's meta-data, such as the title and the author. These two tags are the bare minimum of data required to format your script. However, especially if you're writing a stage play, you may also want to include a dramatis personæ — no problem. For a fully-formatted character page, you can include these lines: 48 49 @persona: Dwarf: an expert cheese-maker. 50 @persona: Giant: a professional baseball-player. 51 @time: The year three million. 52 @setting: Space. 53 54 Include an extra line for each new character in your play. If you're doing a character page, you are also required to include a @time and @setting. 55 56 Next, you'll notice a declaration of which act/scene this is. This is the notation for a stage play, but the convention for a screenplay works the same way. Instead of "ACT I Scene 1" you can just as well write "INT. SPACESHIP" or "EXT. GOLF COURSE". 57 58 Skip this if you're writing a screenplay. If writing a stage play, you must include a paragraph of scene directions that describe the setting. 59 60 Now that you're in the body of the script, each block of text (separated by two new lines) is either one of two things — a paragraph of stage directions or a character speaking. Stage directions describe what's happening. Those are simple enough. The character speaking is where things get fun. 61 62 Each character block starts with the character's name followed by a new line. Then you can write the dialogue itself. Any text in parentheses will be rendered as a character direction, whether its on its own new line or whether it's in the middle of a character's dialogue. You can have as many new lines as you like in the middle of dialogue so that you can put character directions on their own line or break the dialogue up into paragraphs. Either way, do not add a double new line until you're ready for the next stage direction or the next character to speak. 63 64 One thing that isn't generally recommended for scripts, but which I find quite handy, is adding emphasis to a word. If you want to add emphasis, enclose the text *between two asterisks*. This format is very human-readable and the formatter will output the text as underlined. 65 66 Finally, at the very end of your script, you write "The End." — and you're done! Save your script as a plain text, UTF-8 file with a .txt extension and run it through `playfair.pl`. 67 68 ### Example Usage 69 70 ``` 71 swipl --traditional -l playfair.pl -g 'play_to_html' < script.txt > script.html 72 73 # For screenplays. 74 wkhtmltopdf --enable-local-file-access \ 75 --margin-bottom 1in \ 76 --margin-top 1in \ 77 --margin-right 1in \ 78 --margin-left 1.5in \ 79 --page-size letter \ 80 --header-right '[page].' \ 81 --header-font-name Courier \ 82 --header-font-size 10 83 cover cover.html \ 84 page script.html \ 85 script.pdf 86 87 # For stage plays. 88 wkhtmltopdf --enable-local-file-access \ 89 --margin-bottom 1in \ 90 --margin-top 1in \ 91 --margin-right 1in \ 92 --margin-left 1.5in \ 93 --page-size letter \ 94 --header-right 'TITLE / [page]' \ 95 --header-font-name Courier \ 96 --header-font-size 10 97 cover cover.html \ 98 page script.html \ 99 script.pdf 100 ``` 101 102 ## To-Do 103 104 - Playfair is *extremely* slow for long scripts after the 3.0 rewrite. I need to look into this and see what can be done. 105 106 - Even after the 3.0 rewrite a lot of the code is scattered and uncommented. It needs prettying up.