Pangur docsDrafts, sections and versions
A draft is the writing you plan in Plan and write in Write. This page explains how its sections and versions fit together and how a draft differs from the other documents kept in Research.
A draft is a piece of writing that you plan in Plan and write in Write, such as an article, a chapter or a section of a thesis. Pangur stores a draft as a document, which is the same kind of stored object that holds a summary filed from Ask or a literature review written by an assistant. This page explains how a draft is put together, what Pangur keeps as you work, and who can see it. The steps for using the two workspaces are in Plan an argument and Write a draft.
Documents, drafts and research outputs
A document in Pangur is a titled piece of Markdown with a kind, a status and a history of versions. The kinds are summary, literature review, answer, outline and note, and the status is draft, final or archived.
A draft is a document of kind note that you open in Plan or Write. The pickers in those two workspaces list only notes, and New draft… always makes one. Because a draft is a note, it also appears in the Research list under Notes, alongside notes you write by hand.
The other kinds are usually made elsewhere. A summary or an answer is filed from Ask, written by an assistant over MCP, or written by hand in Research (see Research outputs). Any note-kind document can be opened in Plan and Write, including a note written in Research or a note made from a file, as described at the end of this page.
Sections, the working copy
A draft's text is held in sections. A section is one part of the argument, and it has its own title and its own prose along with a few planning fields: a synopsis (the answer to the prompt "What is this part of the argument for?"), a status of outline, draft, revised or done, a word target, a heading level, and a setting that says whether the section is included in the draft or left out of it.
Sections nest, so a chapter can hold subsections. Plan shows the tree as an outline, and Write shows the same tree as a binder for moving around while you write. Because both workspaces edit the same sections, switching from one to the other keeps your place.
The sections are the working copy of the draft. Every change you make in Write is saved to them automatically, a moment after you stop typing, and typing changes nothing else about the draft.
When you open an existing document in Write for the first time, Pangur lifts its whole current text into a single section. It does not split the text at its headings on its own; if you want one section per heading, choose Split at headings in the binder.
Planning material that stays out of the text
Plan attaches two kinds of material to a section, and neither of them ever appears in the written text.
The first is the set of works collected for the section. These are library items you intend to draw on there, each optionally with a page reference, a quotation, a role (Cited, Context or Excluded) and a note on why it is there. Pangur calls attaching a work in this way pinning it. The second is planning notes, which are remarks to yourself about that part of the argument.
Together these make up the plan. They feed Write's desk, which shows the works pinned to the section you are writing, but they are not citations. A citation exists only where you insert one into the prose, as described in Cite and export references.
Versions
A version is a fixed copy of the whole draft at one moment. Edits save themselves to the sections, and a version is made only when you choose Save a version in Write. Saving a version does not stop you editing: the sections stay the working copy, and the version simply records the point you had reached.
To make a version, Pangur's server compiles the sections in order into one Markdown text. Sections left out of the draft are skipped. Each section's title becomes a heading only if the section has a heading level. An unclosed code block is closed, and a figure block that is not valid is turned back into plain text. Figures drawn from a dataset are run again and their rows are stored in the version with the date, so that the version keeps the figures as they were when you saved it. The result is added as the next version, and Pangur also records the version's sources, which are the works pinned to the included sections, once for each work and page reference.
Versions are append-only. Pangur does not overwrite or remove an earlier version unless you delete the whole document, so you can always read an earlier version, and Research's page for the document lists its history.
Revisions made outside Write
Once a document has been opened in Plan or Write, its sections are the text that Write shows. If you then add a version from Research with Revise, or an assistant adds one over MCP, that version is kept in the document's history, but Write goes on showing the sections and does not take the new text into them. In practice this means you should revise drafts in Write, and keep Research's Revise for outputs that you do not edit in sections.
Who can see a draft
Documents, drafts included, belong to one person in one project. Other members of a shared or organisation project do not see your drafts, and a draft in one project does not appear in another (see Projects and libraries).
Connected assistants can create documents and add versions to them, but they cannot edit or delete a document, and they cannot read or change its sections. The full account of what assistants can do is in Assistants and Pangur.
Filing a document in the library
A document can be filed in your library as a note. Pangur renders the current version and adds it to the library, tagged so that it can be found again. The filed note is a rendering, and edits made to it in the library are not saved back to the document.
Drafts started in Plan or Write are not filed automatically, and saving a version in Write does not file it either. Documents created from Ask or by an assistant are filed by default. Filing, and how later versions update the note, is covered in Research outputs.
Making a draft from a file
A Word, OpenDocument, RTF, EPUB or Markdown file that is already in your library can become a draft. Open the file in the item's reader and choose Make a draft. Pangur's server converts the file to Markdown, creates a note-kind document that cites the item as context, and opens the new document's page in Research. The file can be up to 50 MB. In the conversion, images become their alternative text, and footnotes are gathered into a closing "Notes" section.
If the file is in another format, or has no text to convert, Pangur says so and makes nothing.
Source inventories and assistant-submitted analysis
Assistants and the command line can analyse sources with their own models and describe a corpus's sources with a source inventory. This page is the reference for submitting a reading to Pangur and for staging, activating and rolling back an inventory.
Plan an argument
Plan is where you lay a draft out as an outline of sections and collect the works, passages and notes each section will be written from. This page describes the workspace and how to use it.