Metadata-Version: 2.4
Name: schreiblotse
Version: 0.1.0
Summary: Live preview, comments and journal-ready export for scientific manuscripts written in Markdown.
Author: Raviteja Kotikalapudi
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/raviteja.kotikalapudi/schreiblotse
Project-URL: Source, https://gitlab.com/raviteja.kotikalapudi/schreiblotse
Project-URL: Issues, https://gitlab.com/raviteja.kotikalapudi/schreiblotse/-/issues
Project-URL: Changelog, https://gitlab.com/raviteja.kotikalapudi/schreiblotse/-/blob/main/CHANGELOG.md
Keywords: markdown,pandoc,manuscript,academic-writing,latex,citations,bibtex,preview,docx,scientific-writing
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Editors :: Text Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pypandoc-binary>=1.13
Requires-Dist: watchdog>=3.0
Requires-Dist: typst>=0.11
Dynamic: license-file

# schreiblotse

Live preview, comments and journal-ready export for scientific
manuscripts written in Markdown.

A *Lotse* is the harbour pilot who comes aboard and guides a ship
through the channel into port. This does that for a manuscript: it does
not write the paper, it keeps the references intact, the
cross-references honest and the versions straight until the thing is
ready to submit.

## Install

```bash
pip install schreiblotse
```

Or straight from the repository:

```bash
pip install git+https://gitlab.com/raviteja.kotikalapudi/schreiblotse.git
```

Or, without git at all — take the wheel from the
[releases](https://gitlab.com/raviteja.kotikalapudi/schreiblotse/-/releases)
page and install the file:

```bash
pip install schreiblotse-0.1.0-py3-none-any.whl
```

Any of the three is the whole setup. Pandoc and the PDF engine arrive
as Python wheels, so there is no Homebrew step, no TeX install and
nothing to hunt down. Needs Python 3.9 or newer. Written and run on
macOS; the Linux and Windows paths are written but have not been
exercised.

## Use

`lotse init` gives you a folder with four things in it: `manuscript.md`
— your paper, as an empty skeleton with a title block, an abstract and
the usual sections — plus `help.md` (the manual), `references.bib` and
`figures/`.

```bash
lotse init              # start a manuscript in this folder
lotse preview           # live browser preview, rebuilds as you save
lotse build             # PDF and Word into out/

lotse preview help.md   # the manual, in the same reader
```

## The rail

Every tool is one mark in a column on the right. There is nothing else
to find.

| Mark | What it does |
|:--|:--|
| moon / sun | light or dark |
| page marked **PDF** | export a PDF |
| page marked **DOC** | export a Word file |
| page marked **MD** | download the Markdown source |
| blue pen | edit mode — a pen beside every heading and paragraph |
| speech bubble | comments, with the count on its corner |
| two opposed arrows | compare two versions |
| **V** | switch between saved versions |
| quotation marks | citation style: APA, Vancouver, Nature, Chicago |
| bookmark with **+** | add a reference to `references.bib` |
| amber triangle | something is wrong — appears only when it is |

Under them: zoom, the document outline, and **collapse all**. `writing
init` leaves a `help.md` beside your manuscript explaining each one in
context — open it with `lotse preview help.md`.

## What the preview gives you

- **Citations** from `references.bib`, switchable between APA, Vancouver,
  Nature and Chicago without touching the text.
- **Cross-references** — write `@fig:x` and get a clickable "Figure 1".
  Figures, tables and equations number themselves.
- **Comment threads** anchored to selected text, with replies.
  Deleting one saves a version first, so it is undoable.
- **Versions** with a section-by-section comparison that opens over
  the page, and a marked-up PDF or Word file with changes struck and
  underlined — the copy a journal asks for at revision.
- **Section and paragraph editing** — a pen beside each one, so fixing
  the conclusion does not mean scrolling through the introduction.
  Writing in that window saves to the file when you click outside it:
  undo works while it is open, not once it has closed. Save a version
  before a large pass.
- **Line and paragraph numbers** for pointing a co-author at a spot.
- **A bibliography pad** — paste BibTeX from anywhere and it is filed in
  `references.bib`, handing back the citekey to use.
- **Problem checking** — mistyped cross-references, citations with no
  entry and figures whose file has moved are reported in the rail
  instead of reaching the PDF.
- **A standalone HTML copy** from `lotse build`: one file, figures
  embedded, readable anywhere and fine to host.

## Coming next

Versions and comments are the groundwork for the part of writing a
paper that is not writing. Planned: a copy a colleague can open with
nothing installed and comment on — or rewrite a paragraph in, at the
Markdown, so citations survive — and send back, their comments filed
beside yours and their rewrites offered change by change; a
response-to-reviewers document built from the comments and the
comparison; and tracked changes exported as Word's own revisions
rather than as markup.

## Privacy and safety

**Nothing leaves your machine, ever.** Not a citation lookup, not a
font, not a telemetry ping — the package contains no code that opens a
connection, and a test fails if any is added. The preview, the PDF, the
Word file and the HTML copy all render from what is already on disk, so
everything works on a plane, in a hospital network, or with the wifi
switched off.

`pip install` runs no code of its own either: the package has no
install hooks.

**The preview is private.** It serves on loopback, and every request
needs the secret in the URL that `lotse preview` prints. A website
you happen to be visiting cannot read your manuscript or write to it:
reads need the token, and writes need it in a header no cross-origin
page can set. Dotfiles are never served, so a preview started inside a
repository does not hand out `.git/config`. If you bind to a real
interface with `--host` to show a co-author, the link is the password —
without it they get a `403`.

## Settings

`defaults.yaml` in your folder holds the settings worth changing —
fonts, margins, cross-reference wording. Everything structural lives in
the package, so that file stays small and safe to edit.

## Development

```
src/schreiblotse/   the package
  cli.py               preview, build, init
  app.py               the preview server
  render.py            every pandoc invocation, in one place
  blocks.py            where a section starts and a paragraph ends
  watch.py             rebuild on save
  bib_add.py           what the paste box does
  problems.py          what pandoc renders but nobody meant
  paths.py             package assets against the author's folder
  assets/              templates, CSL styles, the starter manuscript
tests/                 the suite: no dependencies, no network
example/               the manual, as a working manuscript
```

```bash
python3 -m unittest discover -s tests -p 'test_*.py'   # the suite
cd example && ../preview.sh                           # from a checkout
python3 -m pip wheel --no-deps -w dist .              # the wheel
```
