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

pip install schreiblotse

Or straight from the repository:

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

Or, without git at all — take the wheel from the releases page and install the file:

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/.

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.

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

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