txtdown 0.2.0__tar.gz

txtdown-0.2.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-06-20
+
+First public release.
+
+### Added
+- **Cross-source quotation markup.** Lines beginning with `>` are parsed as verbatim
+  quotations of other literary sources; the marker is stripped and the line is flagged
+  with `Line.is_quote`. Consecutive `>` lines form a multi-line quotation. Round-trips
+  through `write()`. Demonstrated by the Cicero (quoting Ennius/Terence) and Augustine
+  (quoting Virgil) examples.
+- **Speaker markup for dramatic texts.** `@Speaker:` at the start of a line extracts the
+  speaker into `Line.speaker` and keeps `Line.text` as clean speech (single-word names).
+- **Explicit line numbering.** Leading `N.` prefixes override auto-increment, and trailing
+  editorial labels (e.g. `983a`) are captured in `Line.label` and usable in citations.
+- **Strict validation.** `parse()` now requires a YAML front matter block with a `work`
+  field and raises `ValueError` when either is missing. Pass `parse(..., strict=False)` to
+  parse a fragment (single line or section) without metadata.
+- `examples/cicero-de-amicitia.txtd` — full *Laelius de Amicitia* with cross-source quotes.
+
+## [0.1.0] - Initial format
+
+- YAML front matter metadata (`author`, `work`, `source`, `scope`, plus arbitrary extras).
+- Sections separated by `---`, with auto-numbering, explicit IDs, and optional titles.
+- Auto-numbered lines with 1-indexed, citation-based access (`doc.get("2.3")`).
+- Round-trip-safe `parse()` / `write()`.
+
+[0.2.0]: https://github.com/diyclassics/txtdown/releases/tag/v0.2.0

txtdown-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018-2026 Patrick J. Burns
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

txtdown-0.2.0/MANIFEST.in

@@ -0,0 +1,13 @@
+# Make the sdist a coherent, self-testing source release:
+# include the test suite with its fixtures, the example corpus, and the changelog
+# so downstream packagers can run the tests against the packaged source.
+graft tests
+graft examples
+include CHANGELOG.md
+include LICENSE
+include README.md
+
+# Never ship caches or compiled artifacts.
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude .DS_Store

txtdown-0.2.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: txtdown
+Version: 0.2.0
+Summary: Minimal markup for Latin text collections
+Author: Patrick J. Burns
+License: MIT
+Project-URL: Homepage, https://github.com/diyclassics/txtdown
+Project-URL: Repository, https://github.com/diyclassics/txtdown
+Project-URL: Changelog, https://github.com/diyclassics/txtdown/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/diyclassics/txtdown/issues
+Keywords: latin,markup,text,philology,digital-humanities,nlp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# txtdown
+
+Minimal markup for Latin text collections using human-readable markup with inferrable hierarchical structure for scholarly citation.
+
+## Installation
+
+```bash
+pip install git+https://github.com/diyclassics/txtdown.git
+```
+
+## Quick Start
+
+```python
+from txtdown import parse, write
+
+# Parse a .txtd file
+doc = parse("sulpicia.txtd")
+
+# Access metadata
+print(doc.metadata.author)  # "Sulpicia"
+print(doc.metadata.work)    # "Epistulae"
+
+# Access by citation
+line = doc.get("2.3")       # Section 2, line 3
+section = doc.get("1")      # Entire section 1
+
+# Iterate sections and lines
+for section in doc.sections:
+    for line in section.lines:
+        print(f"{section.id}.{line.number}: {line.text}")
+
+# Write back to file (round-trip safe)
+write(doc, "output.txtd")
+```
+
+## Format Specification
+
+A `.txtd` file consists of a YAML front matter block followed by sections separated by horizontal rules (`---`). The front matter block is required and must include a `work` field; `parse()` raises `ValueError` otherwise. To parse a fragment without metadata (e.g. a single line or section), pass `strict=False`.
+
+### Basic Structure
+
+```
+---
+author: Sulpicia
+work: Epistulae
+source: https://thelatinlibrary.com/sulpicia.html
+---
+
+--- 1
+
+Tandem venit amor, qualem texisse pudori
+    quam nudasse alicui sit mihi fama magis.
+exorata meis illum Cytherea Camenis
+    attulit in nostrum deposuitque sinum.
+etc.
+
+--- 2
+
+Invisus natalis adest, qui rure molesto
+    et sine Cerintho tristis agendus erit.
+etc.
+```
+
+### Sections
+
+- Sections are separated by `---` (three or more hyphens)
+- Sections auto-number (1, 2, 3...) unless given explicit IDs (best practice)
+- Explicit section ID: `--- prooemium` or `--- 1a`
+- Section with title: `--- prooemium: Introduction`
+
+### Lines (for verse)
+
+- Lines auto-number within each section (1, 2, 3...)
+- Blank lines don't count toward line numbering
+- Access via citation: `doc.get("2.3")` returns section 2, line 3
+
+**Line indentation** (`mode: verse`): Leading whitespace indicates poetic structure (e.g., pentameter lines in elegiac couplets):
+
+```
+Tandem venit amor, qualem texisse pudori
+    quam nudasse alicui sit mihi fama magis.
+```
+
+The parser preserves indentation. For NLP, TxtdownReader strips leading whitespace when joining lines for sentence segmentation.
+
+### Speaker Markup (dramatic texts)
+
+For dramatic texts, use `@Speaker:` at the start of a line to mark speaker attribution:
+
+```
+@Diocletianus: Quid sibi vult ista, quae vos agitat, fatuitas?
+@Agapes: quod signum fatuitatis nobis inesse deprehendis?
+@Diocletianus: Evidens magnumque.
+```
+
+The parser extracts the speaker name into `line.speaker` and keeps `line.text` as pure speech text — ideal for NLP pipelines that need clean text without markup.
+
+```python
+doc = parse("dulcitius.txtd")
+for line in doc.sections[0].lines:
+    print(f"{line.speaker}: {line.text}")
+# Diocletianus: Quid sibi vult ista...
+```
+
+Non-speaker lines (stage directions, prose) have `line.speaker = None`. Speaker markup round-trips through `write()`.
+
+### Cross-source Quotation
+
+Use `>` at the start of a line to mark text quoted verbatim from *another* literary
+source — an author embedding a poet's verse in their own prose, for example. This
+repurposes the familiar blockquote convention for the citational habits of classical texts:
+
+```
+Quamquam Ennius recte:
+
+> Amicus certus in re incerta cernitur,
+
+tamen haec duo levitatis et infirmitatis plerosque convincunt.
+```
+
+The parser strips the `>` marker and flags the line with `line.is_quote = True`, keeping
+`line.text` as clean quoted text. Consecutive `>` lines form a multi-line quotation:
+
+```
+> Negat quis, nego; ait, aio; postremo imperavi egomet mihi
+> Omnia adsentari,
+```
+
+```python
+doc = parse("cicero-de-amicitia.txtd")
+quotes = [line.text for s in doc.sections for line in s.lines if line.is_quote]
+# ['Amicus certus in re incerta cernitur,', ...]
+```
+
+Non-quote lines have `line.is_quote = False`. Quotation markup round-trips through `write()`.
+See `examples/cicero-de-amicitia.txtd` (Cicero quoting Ennius and Terence) and
+`examples/augustine-civ-dei-1.2.txtd` (Augustine quoting Virgil).
+
+### Metadata
+
+| Field | Description |
+|-------|-------------|
+| `work` | Work title (**required**) |
+| `author` | Author name |
+| `source` | Source URL or reference |
+| `scope` | Portion of work in file (e.g., `1-6` for books 1-6) |
+
+Additional fields are preserved in `metadata.extras`.
+
+## API Reference
+
+### Functions
+
+- `parse(path_or_content: str, *, strict: bool = True) -> Document` — Parse a `.txtd` file or string. Strict by default: raises `ValueError` if the front matter block or `work` field is missing; pass `strict=False` for fragments.
+- `write(doc: Document, path: str | None) -> str` — Write to file if path given; always returns serialized string
+
+### Classes
+
+- `Document` — Container with `metadata: Metadata` and `sections: list[Section]`
+- `Section` — Container with `id: str`, `lines: list[Line]`, optional `title` and `metadata`
+- `Line` — Container with `text: str`, `number: int`, optional `speaker: str | None` and `label: str | None`, and `is_quote: bool` (cross-source quotation)
+- `Metadata` — Container with `author`, `work`, `source`, `scope`, and `extras` dict
+
+## Development
+
+```bash
+# Clone and install dev dependencies
+git clone https://github.com/diyclassics/txtdown.git
+cd txtdown
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=txtdown --cov-report=term-missing
+```
+
+## Project History
+
+The idea for txtdown originated in January 2018, inspired by the need for a document format for Latin text collections that balanced the simplicity of plaintext with the more involved markup of XML-based formats like TEI. The goal was to create a format that is both human-readable and computer-tractable, supporting hierarchical structures, fundamental annotations, and embedded metadata. Txtdown has since been influenced by ongoing work on annotation projects such as the [Representing Women Authorship in the Latin Treebanks (RWALT)](https://diyclassics.github.io/rwalt-site/) project.
+
+## License
+
+MIT

txtdown-0.2.0/README.md

@@ -0,0 +1,185 @@
+# txtdown
+
+Minimal markup for Latin text collections using human-readable markup with inferrable hierarchical structure for scholarly citation.
+
+## Installation
+
+```bash
+pip install git+https://github.com/diyclassics/txtdown.git
+```
+
+## Quick Start
+
+```python
+from txtdown import parse, write
+
+# Parse a .txtd file
+doc = parse("sulpicia.txtd")
+
+# Access metadata
+print(doc.metadata.author)  # "Sulpicia"
+print(doc.metadata.work)    # "Epistulae"
+
+# Access by citation
+line = doc.get("2.3")       # Section 2, line 3
+section = doc.get("1")      # Entire section 1
+
+# Iterate sections and lines
+for section in doc.sections:
+    for line in section.lines:
+        print(f"{section.id}.{line.number}: {line.text}")
+
+# Write back to file (round-trip safe)
+write(doc, "output.txtd")
+```
+
+## Format Specification
+
+A `.txtd` file consists of a YAML front matter block followed by sections separated by horizontal rules (`---`). The front matter block is required and must include a `work` field; `parse()` raises `ValueError` otherwise. To parse a fragment without metadata (e.g. a single line or section), pass `strict=False`.
+
+### Basic Structure
+
+```
+---
+author: Sulpicia
+work: Epistulae
+source: https://thelatinlibrary.com/sulpicia.html
+---
+
+--- 1
+
+Tandem venit amor, qualem texisse pudori
+    quam nudasse alicui sit mihi fama magis.
+exorata meis illum Cytherea Camenis
+    attulit in nostrum deposuitque sinum.
+etc.
+
+--- 2
+
+Invisus natalis adest, qui rure molesto
+    et sine Cerintho tristis agendus erit.
+etc.
+```
+
+### Sections
+
+- Sections are separated by `---` (three or more hyphens)
+- Sections auto-number (1, 2, 3...) unless given explicit IDs (best practice)
+- Explicit section ID: `--- prooemium` or `--- 1a`
+- Section with title: `--- prooemium: Introduction`
+
+### Lines (for verse)
+
+- Lines auto-number within each section (1, 2, 3...)
+- Blank lines don't count toward line numbering
+- Access via citation: `doc.get("2.3")` returns section 2, line 3
+
+**Line indentation** (`mode: verse`): Leading whitespace indicates poetic structure (e.g., pentameter lines in elegiac couplets):
+
+```
+Tandem venit amor, qualem texisse pudori
+    quam nudasse alicui sit mihi fama magis.
+```
+
+The parser preserves indentation. For NLP, TxtdownReader strips leading whitespace when joining lines for sentence segmentation.
+
+### Speaker Markup (dramatic texts)
+
+For dramatic texts, use `@Speaker:` at the start of a line to mark speaker attribution:
+
+```
+@Diocletianus: Quid sibi vult ista, quae vos agitat, fatuitas?
+@Agapes: quod signum fatuitatis nobis inesse deprehendis?
+@Diocletianus: Evidens magnumque.
+```
+
+The parser extracts the speaker name into `line.speaker` and keeps `line.text` as pure speech text — ideal for NLP pipelines that need clean text without markup.
+
+```python
+doc = parse("dulcitius.txtd")
+for line in doc.sections[0].lines:
+    print(f"{line.speaker}: {line.text}")
+# Diocletianus: Quid sibi vult ista...
+```
+
+Non-speaker lines (stage directions, prose) have `line.speaker = None`. Speaker markup round-trips through `write()`.
+
+### Cross-source Quotation
+
+Use `>` at the start of a line to mark text quoted verbatim from *another* literary
+source — an author embedding a poet's verse in their own prose, for example. This
+repurposes the familiar blockquote convention for the citational habits of classical texts:
+
+```
+Quamquam Ennius recte:
+
+> Amicus certus in re incerta cernitur,
+
+tamen haec duo levitatis et infirmitatis plerosque convincunt.
+```
+
+The parser strips the `>` marker and flags the line with `line.is_quote = True`, keeping
+`line.text` as clean quoted text. Consecutive `>` lines form a multi-line quotation:
+
+```
+> Negat quis, nego; ait, aio; postremo imperavi egomet mihi
+> Omnia adsentari,
+```
+
+```python
+doc = parse("cicero-de-amicitia.txtd")
+quotes = [line.text for s in doc.sections for line in s.lines if line.is_quote]
+# ['Amicus certus in re incerta cernitur,', ...]
+```
+
+Non-quote lines have `line.is_quote = False`. Quotation markup round-trips through `write()`.
+See `examples/cicero-de-amicitia.txtd` (Cicero quoting Ennius and Terence) and
+`examples/augustine-civ-dei-1.2.txtd` (Augustine quoting Virgil).
+
+### Metadata
+
+| Field | Description |
+|-------|-------------|
+| `work` | Work title (**required**) |
+| `author` | Author name |
+| `source` | Source URL or reference |
+| `scope` | Portion of work in file (e.g., `1-6` for books 1-6) |
+
+Additional fields are preserved in `metadata.extras`.
+
+## API Reference
+
+### Functions
+
+- `parse(path_or_content: str, *, strict: bool = True) -> Document` — Parse a `.txtd` file or string. Strict by default: raises `ValueError` if the front matter block or `work` field is missing; pass `strict=False` for fragments.
+- `write(doc: Document, path: str | None) -> str` — Write to file if path given; always returns serialized string
+
+### Classes
+
+- `Document` — Container with `metadata: Metadata` and `sections: list[Section]`
+- `Section` — Container with `id: str`, `lines: list[Line]`, optional `title` and `metadata`
+- `Line` — Container with `text: str`, `number: int`, optional `speaker: str | None` and `label: str | None`, and `is_quote: bool` (cross-source quotation)
+- `Metadata` — Container with `author`, `work`, `source`, `scope`, and `extras` dict
+
+## Development
+
+```bash
+# Clone and install dev dependencies
+git clone https://github.com/diyclassics/txtdown.git
+cd txtdown
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=txtdown --cov-report=term-missing
+```
+
+## Project History
+
+The idea for txtdown originated in January 2018, inspired by the need for a document format for Latin text collections that balanced the simplicity of plaintext with the more involved markup of XML-based formats like TEI. The goal was to create a format that is both human-readable and computer-tractable, supporting hierarchical structures, fundamental annotations, and embedded metadata. Txtdown has since been influenced by ongoing work on annotation projects such as the [Representing Women Authorship in the Latin Treebanks (RWALT)](https://diyclassics.github.io/rwalt-site/) project.
+
+## License
+
+MIT

txtdown-0.2.0/examples/augustine-civ-dei-1.2.txtd

@@ -0,0 +1,29 @@
+---
+author: Augustine of Hippo
+work: De Civitate Dei
+source: https://www.thelatinlibrary.com/augustine/civ1.shtml
+scope: 1.2
+language: la
+mode: prose
+genre: theology
+comment: This example demonstrates the use of `>` for indicating in-text quotation.
+---
+
+--- 2
+
+Tot bella gesta conscripta sunt uel ante conditam Romam uel ab eius exortu et imperio: legant et proferant sic aut ab alienigenis aliquam captam esse ciuitatem, ut hostes, qui ceperant, parcerent eis, quos ad deorum suorum templa confugisse compererant, aut aliquem ducem barbarorum praecepisse, ut inrupto oppido nullus feriretur, qui in illo uel illo templo fuisset inuentus. Nonne uidit Aeneas Priamum per aras
+
+> Sanguine foedantem quos ipse sacrauerat ignes?
+
+Nonne Diomedes et Vlixes
+
+>   caesis summae custodibus arcis.
+> Corripuere sacram effigiem manibusque cruentis
+> Virgineas ausi diuae contingere uittas?
+
+Nec tamen quod sequitur uerum est:
+
+> Ex illo fluere ac retro sublapsa referri
+> Spes Danaum.
+
+Postea quippe uicerunt, postea Troiam ferro ignibusque delerunt, postea confugientem ad aras Priamum obtruncauerunt. Nec ideo Troia periit, quia Mineruam perdidit. Quid enim prius ipsa Minerua perdiderat, ut periret? an forte custodes suos? Hoc sane uerum est; illis quippe interemptis potuit auferri. Neque enim homines a simulacro, sed simulacrum ab hominibus seruabatur. Quomodo ergo colebatur, ut patriam custodiret et ciues, quae suos non ualuit custodire custodes?