Skip to content

Send/Receive and Paratext's memory

Aquilla does not send or receive Paratext changes itself. Paratext does. Aquilla edits the Paratext project files on your computer. You then run Send/Receive in Paratext, and Paratext shares the changes with your team in the same way it shares any edit. Aquilla never runs Send/Receive and never touches the project’s history.

flowchart LR
  A["You edit in Aquilla"] --> B["Write to Paratext"]
  B --> C["Paratext project folder on your computer"]
  C --> D["Send/Receive in Paratext"]
  D --> E["Your team's Paratext"]
  E --> D
  D --> C
  C -- "Aquilla watches the folder" --> A
  1. You edit a verse in Aquilla.
  2. You choose Write to Paratext. Aquilla changes only the words you edited in the book file.
  3. You run Send/Receive in Paratext. Your edit goes to your team.
  4. When a teammate’s change arrives, Paratext writes it into the same folder. Aquilla watches the folder, and the change shows up in the book you have open.

Why a teammate sees nothing until Send/Receive

Section titled “Why a teammate sees nothing until Send/Receive”

Paratext is a shared project with one copy on each person’s computer. Writing to the file on your computer does not reach your team. Only Send/Receive does that. This is how Paratext works for any edit, not only edits from Aquilla.

Paratext keeps the books that are open in its own memory. When someone edits one of those books in Paratext, Paratext saves the book from that memory copy. If Aquilla wrote to the book after Paratext loaded it, the next Paratext save can put the old text back over your edit. The edit looks lost, but it is only replaced by an old copy.

Aquilla expects this and protects you:

  1. It notices. Aquilla records what each verse said before and after its own write. If the file later returns to the “before” text, Aquilla knows that Paratext reverted your edit.
  2. It keeps your version. Aquilla shows a window called Paratext changed this too. It lists the verses side by side: When you opened it, Paratext now and Yours. Your version is already selected.
  3. You choose. Pick Keep mine or Take theirs for each verse, or Keep all mine or Take all theirs for the whole book.
  4. It puts the book on hold. If Aquilla wrote your text back at once, Paratext could revert it again. So the book waits. Close or reload the book in Paratext, then choose I reloaded it in Paratext. Aquilla then writes your chosen text.

Nothing is lost at any step. Aquilla keeps both versions until you decide.

What if my teammate and I edit the same verse?

Section titled “What if my teammate and I edit the same verse?”

Two kinds of overlap can happen:

  • Both of you changed the verse. Aquilla shows the same Paratext changed this too window with the three versions. You pick one.
  • You edited and Send/Receive brought a different edit for that verse. Aquilla treats it the same way. The verse waits for your choice. It does not overwrite anything silently.

For edits that Paratext itself cannot merge, Paratext shows its own conflict. That part stays in Paratext.

Each time you choose Write to Paratext, Aquilla:

  1. reads the file again, so it starts from what is on disk now;
  2. checks that Paratext lets your user edit this book and chapter;
  3. changes only the verses you edited, and leaves every other byte alone;
  4. checks its own result, and refuses to save if more than your edits changed;
  5. holds back an edit that adds or removes a footnote or cross reference marker, until you choose Write it anyway; and
  6. keeps a copy of the previous file outside the project folder.

If a check fails, Aquilla writes nothing and tells you why. The page Working on your Paratext projects says where the backup copies are.

Can I use Aquilla while Paratext is running?

Section titled “Can I use Aquilla while Paratext is running?”

Yes. Aquilla shows Paratext is running or Paratext is not running so you can see which case you are in. The safest order is to close the book in Paratext first. If you do not, expect the hold described above when Paratext saves the same book.

  • It does not run Send/Receive, create commits or change project history.
  • It does not edit or resolve existing Paratext notes. See Notes.
  • It does not change term renderings or project progress.
  • It does not connect to Paratext’s online servers or to Scripture Forge. It works with the project files on your computer.