Talmudifier

Talmudifier is a Python module that will procedurally generate page layouts similar to the Talmud.

<img src="images/sample_page.png" style="zoom:75%;" />

That .PDF was generated from this input file.

1. Who is this for?

This is primarily for people familiar with Markdown, Python, LaTeX, and medieval typesetting. There might not be many of these people. You should at minimum:

1. Have some experience with opening files and parsing strings in Python.
2. Feel comfortable installing LaTeX packages. (You won't use LaTeX directly, so you don't need to learn any of its syntax.)
3. Have at least a cursory understanding of why the Talmud is typeset the way it is.

If you don't want to code, that's OK! See "Non-Coders" 4. Usage.

Please help me improve this README. I wrote this README initially just so that I could remember how the program works. There's probably a lot missing, and a lot that is very misleading... So, please email me with suggestions for improving the documentation (or, better yet, create a GitHub Issue if you know how).

2. Requirements

• Windows, OS X, or Linux
• Python 3.6 or 3.7
• XeLaTeX
  • marginnote
  • sectsty
  • ragged2e
  • lineno
  • xcolor
  • paracol
  • fontspec
  • scrbook

If you're not sure how to install anything and Google isn't being helpful, you can email me.

3. Setup

1. Open the terminal.

| Windows | OS X | Linux | | -------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------ | | Search for "powershell" in the start menu. Run it. | In Spotlight, search for "Terminal". Run it. | Depends; if you're not sure how to do this, email me. |

2. In the terminal, type:

cd ~/<where this folder is>/talmudifier

For example, if this folder is in Downloads/RandomStuff:

cd ~/Downloads/RandomStuff/talmudifier

3. In the terminal, type:

pip3 setup.py -e .

Don't forget the . at the end! This will install the Talmudifier Python module.

4. In the terminal, try creating a test page.

| Windows | OS X | Linux | | ---------------------------- | ------------------------------ | ------------------------------ | | py -3 test_input_reader.py | python3 test_input_reader.py | python3 test_input_reader.py |

If this test script works, then everything is set up OK. The script will generate:

• The test page PDF: talmudifier/Output/test_page.pdf
• The .tex file used to create the PDF: talmudifier/Output/test_page.tex
• A few other files in Output/ that you can ignore.

4. Usage

Coders:

Talmudifier requires three sources of markdown text. It doesn't care where the sources come from as long as they are imported correctly. (In other words, you're on your own providing the text and slotting it into this program.)

left = "This is one source of text."
center = "This is another source of text."
right = "To be honest, you'll need a lot more words per column for this to work right."

Or just pull the text from three files, e.g.:

import io

with io.open("left.txt", "rt", encoding="utf-8") as f:
    left = f.read()

Then import Talmudifier and generate a .pdf:

from talmudifier.talmudifier import Talmudifier

t = Talmudifier(left, center, right)
t.create_pdf()

Non-coders:

1. Edit the test input file talmudifier/test/test_input.md
2. Run test_input_reader.py (see 3. Setup)

5. API

Talmudifier

Generate Talmud-esque page layouts, given markdown plaintext and a recipe JSON file.

from talmudifier.talmudifier import Talmudifier

t = Talmudifier(left, center, right)

__init__(self, text_left: str, text_center: str, text_right: str, recipe_filename="default.json")

| Parameter | Description | | --- | --- | | text_left | The markdown text of the left column.| | text_center | The markdown text of the center column.| | text_right | The markdown text of the right column.| | recipe_filename | The filename of the recipe, located in recipes/|

---

get_tex(self) -> str

Generate the body of text.

1. Create 4 rows on the left and right (width = one half).
2. Create 1 row on the left and right (width = one third).
3. Until the columns are all done: Find the shortest column and add it. Add other columns up to that length.

---

get_chapter(self, title: str) -> str

Returns the chapter command.

| Parameter | Description | | --- | --- | | title | The title of the chapter.|

---

create_pdf(self, chapter="", output_filename="output", print_tex=False) -> str

Create a PDF. Generate the chapter and the body, and append them to the preamble. Returns the LaTeX string.

| Parameter | Description | | --- | --- | | chapter | If not empty, create the header here.| | output_filename | The name of the output file.| | print_tex | If true, print the LaTeX string to the console.|

PDFWriter

Given LaTeX text, write a PDF. A Talmudifier object has its own writer, but it might be useful for you to create .pdfs manually (especially if you want to stitch a lot of .tex files together).

from talmudifier.pdf_writer import PDFWriter

writer = PDFWriter(preamble)

__init__(self, preamble: str)

| Parameter | Description | | --- | --- | | preamble | The preamble text.|

---

write(self, text: str, filename: str) -> str

Create a PDF from LaTeX text. Returns the LaTeX text, including the preamble and the end command(s).

| Parameter | Description | | --- | --- | | text | The LaTeX text.| | filename | The filename of the PDF. |

6. Recipes

A recipe is a JSON file that defines the fonts and other styling rules for your page. It is functionally the same as just writing your own TeX preamble, but probably a lot more user-friendly.

By default, talmudifier.py uses: recipes/default.json.

All custom recipes should be saved to the recipes/ directly as .json files.

fonts

Definitions for the font per column.

"fonts":
{
    "left":
    {
        
    }
}

Key = The name of the font (left, center, right). Don't change these.

| Field | Type | Description | Required? | | ------------------ | ---------- | ------------------------------------------------------------ | --------- | | path | string | Path to the directory of fonts relative to talmudifier.py. | ✔ | | ligatures | string | How ligatures are handled. This should probably always be "TeX". There are other options, but the documentation for them is sparse. | ✔ | | regular_font | string | The regular font file. Must be a file located in the directory path. | ✔ | | italic_font | string | The italic font file. Must be a file located in the directory path. | ❌ | | bold_font | string | The bold font file. Must be a file located in the directory path. | ❌ | | bold_italic_font | string | The bold+italic font file. Must be a file located in the directory path. | ❌ | | size | integer | The font size. This will default to whatever the font size is in the header.txt preamble. If skip is not included, this is ignored. | ❌ | | skip | integer | The size of the spacing between two lines. Generally you want this to be 2 more than size. If size is not included, this is ignored. | ❌ | | substitutions | dictionary | Per word in this column, replace every key in the dictionary with the value. | ❌ | | citation | dictionary | The recipe for citations pointing to this column. See below. | ❌ |

citation

Citations are letters or words that direct the reader from column to column.

| Field | Type | Description | Required? | | -------------- | ----------------- | ------------------------------------------------------------ | --------- | | path | string | Path to the directory of fonts relative to talmudifier.py. | ✔ | | font | string | The font file. Must be a file located in the directory path. | ✔ | | command | string | The command used in the TeX document body to start the citation font. This can be the same as font_command but you might want to define a custom version. default.json does have a custom version, that makes citations red-colored. | ✔ | | font_command | string | The command used to name the font family. You probably don't want to change this from default.json's values. | ✔ | | pattern | string<br>(regex) | talmudifier.py will replace anything in the input string with this regex pattern with a properly-formatted citation letter. | ✔ |

character_counts

These are the average number of characters in a column across many trials, given different column configurations (e.g. left and right only), a target column (e.g. left), and a target number of rows (e.g. 1).

talmudifier.py will use these numbers to fill columns with a "best guess" number of words before adding and subtracti