Workflowy Text Outline Tool

Ephraim Damboritz edited this page Sep 27, 2016 · 11 revisions
This tool is designed to allow the easy creation of a complex text in Sefaria by using Workflowy.

This tool can be used to create a table of contents for a text (an Index record in Sefaria), and to even fill in simple text to go in the text being described by the table of contents (a text, or Version record, in Sefaria).

Using Workflowy to design texts in Sefaria is done in two main steps: 1. Creating a Workflowy document representing the text 2. Running a programmatic script to import said structure into Sefaria.

Step 1. Preparing the Workflowy Document:

Worklfowy stores nodes in outline form. The parsing script mentioned above will utilize this form to create a layered table of contents.

  1. First create a new Workflowy Document.
  2. Then add a SINGLE bullet to the main page containing the Title of the book being described (All other bullets describing the internal structure of the text MUST be nested under this bullet). Separate the English title from the Hebrew title (both are required) by using the forward slash / character on the keyboard. If you wish to add alternate English or Hebrew titles, please group each language together (i.e. do not write one English then one Hebrew and then another in English) separated by the / character. Each of the languages should internally separate the alternate title variations using the pipe | character (usually above the enter key).
  3. If you wish to specify which categories in the Sefaria table of contents (e.g. Talmud->Bavli->Seder Zeraim), please add them to the root bullet, after the titles. Surround this categories text with the percent sign %. The categories themselves should be separated from each other by a forward slash / (e.g. Talmud/Bavli/Seder Zeraim).
  4. Proceed to add nested bullets as needed to describe the text structure. The same rules of adding titles apply to all the nested bullets.
  5. NOTES:
    1. Please do NOT use a hyphen - or a forward slash / as part of any title. The titles are used to craft URLs to Sefaria and these are illegal characters inside a URL.
    2. Please do NOT use any character used as a delimiter between titles (the pipe character or the forward slash again) inside titles as well. This will break the parsing script.
    3. Should you need to make a comment that will not be parsed, please place the text surrounded by the pound sign # parentheses. It will then be ignored.

Example:

  • Siddur A / סידור א
    • Shacharit / תפילת שחרית
    • Minchah / תפילת מנחה
    • Maariv|Arvit / מעריב|ערבית
      • Vehu Rachum / והוא רחום

Note on amount of sub-sections in the deeper-most bullets:

The deepest bullet at any point will be the one where text is actually stored on. By default this means that you can only create a series of paragraphs at a single level of depth at this point. For example a bullet titled "The Tale of the Four Kings" will only be able, unless specified, to have "The Tale of the Four Kings.1", "The Tale of the Four Kings.2" etc. This means that if you want a certain bullet title to also use numeric continuation at a depth larger than one (such as Chapter and Verse), you must specify this in square brackets [] after the titles.
Examples:

  1. using only a number to denote depth

    • Midrash on Kings
      • Introduction
      • The Tale of the Four Kings [2]
  2. using section names (and the depth is implied from the number of section names):

    • Midrash on Kings
      • Introduction
      • The Tale of the Four Kings ['Chapter', 'Verse']
  3. using both section names and types:

    • Midrash on Kings
      • Introduction
      • The Tale of the Four Kings ["Chapter:Integer", "Verse:Integer"]

Note on Default titles:

Sometimes you will find yourself with a structure like this:

  • The Tale of the Four Kings
    • Introduction
    • The Tale of the Four Kings

In such a case, we use a notion called a default node in order to eliminate the title repetition. To accomplish this, simply replace the redundant title with the special string **default**:

  • The Tale of the Four Kings
    • Introduction
    • **default**

Optional Step: Adding optional text to the Workflowy ouline

In some cases, entering the version text into the Workflowy, rather than later through the Sefaria GUI might be preferred. If so, text can be added to outline nodes using the Workflowy "add note" feature. Simply hover the cursor over the appropriate bullet and select "add note". Please note that only text that is not broken into more than one level of depth can be added (.e.g. a list of verses can be added, but a list of chapters with verses inside them cannot)

A few standards are used by this script when parsing:

  • Text inside parenthesis [()] - is italicized (<em>).
  • A paragraph break [ie: the enter key] separates paragraphs.
  • Forward slashes [/] are interpreted as line breaks.
  • if you need to list version attributes (i.e. versionTitle, versionSource, etc) use the notes on the primary text title (the topmost title- for the whole book) as that will usually not have other text under it.

Exporting the Workflowy:

To export, simply hover the cursor over the bullet of a root node in the Workflowy. Select "export" and choose opml. Save to opml file.

2. Running the Script

The parsing script is called parse_index_and_version.py.

The script requires the name of the opml export file from Workflowy as its primary argument. These flags (in any order) are optional:

  • -t stores all titles/nodes in opml as shared terms (not including root). Useful in some rare instances including Sefaria's Siddur.
  • -i creates an Index record for this schema. If the -i option is not given the serialized schema will be returned on standard out.
  • -v saves text stored in opml in the form of Workflowy notes to a version of the text. see step 2 If there is no existing Index record for the text, created either by using -i or pre-existing, then the Version creation will fail.

So, for example, running the script might look like this:

python parse_index_and_version.py ashkenaz.opml -i -v