What's New

File 1061

Lost Sheep

I have a lot of ground to cover here but I think it will be valuable to most Paratext 7 users to read this carefully. Let me start with something I saw a long time ago (altho I don't recall the markup exactly):

\q1 Little Bo Peep has lost her sheep
\q2 And doesn't know where to find them.

If you have been involved with Bible Translation for more than a few weeks you have probably at one time or another experienced some of your text going lost just like Ms. Peep's sheep. Text may go missing due to hardware failure, insufficiently omniscient programmer error, or even "I can't believe I just did that" error. What to do?

Shepherding Sheep the Old Way

How did we shepherd our sheep in Paratext 6 and before? Whenever you thot about it you made a File/Backup. Any time later if you wanted some translated text back you went to the correct zip file and File/Restore'd it back out. This system works well as long as:

a) You always remember to make a backup whenever a significant amount of work has been done

b) You keep the backup in some safe place

c) You label each backup as to its contents in a totally clear manner

d) You are willing to potentially look through a lot of zip files to find the version you want

e) You never accidentally restore from the wrong zip file or restore too much or too little from the right zip file

f) You make sure that it never happens that two people edit the same book on different machines at the same time, otherwise when you transfer the book from one machine to the other somebody's changes will be lost.

So ... if you have great organizational skills and never forget to exercise them and have a lot of time to devote to data administration ... everything is good. Fail in this and your sheep may not only be missing they may just be gone forever.

Shepherding Sheep the New Way

How do we try to do this better in Paratext 7? Hidden away in the mysterious .Hg subdirectory of each project is a thing called a "Repository". We do the following with it; note that a-f) here correspond to how the new way P7 tries to reduce the risks associated with old way points a-f) above.

a) The first time you make any change to a project text file each day we make a copy of the entire project into the repository. This copy is done in a very clever way that does not take up much space, essentially just storing what has changed since the previous copy. In addition whenever a dangerous operation is about to be performed you are prompted as to whether you would like to make a copy in the repository ... just in case you later decide you want to go back. Finally at any point in time you can use the command Project > Mark Point in Project History to make a copy of the project and give some info to identify it, e.g. "At end of Tuesday's checking with Alfonse". In essence the repository, although it stays small, ends up with 100's of copies of your project as it existed at various times on various machines.

b) The repository is always kept in the same place in the project directory. Using one of the File > Send / Receive commands you can easily make a copy of the repository on a USB data key, another drive on the network, or the UBS file server sitting out on the internet somewhere in North America. This will be a big comfort to you on the day your laptop gets dropped in a mud puddle.

c) When you Mark Point in Project History you have the opportunity to carefully label a copy.

d) There is help to quickly find the lost data you are looking for, see the FINDING SHEEP section below.

e) The system always keeps track of what has changed and allows you to move the changes to another machine. The system makes it difficult to accidentally write old data over the top of new data.

f) If two people edit the same book on different machines the system will automatically merge their changes keeping both as long as they do not both edit the same verse. If they do edit the same verse rather than just losing one copy of the verse the system will keep one copy and make the other version of the verse available via Project > Show Conflicts. This merge facility is intended as a "safety net". Normally a project should use administrative means to ensure that two people are not working on the same verse at the same time.

Summary: The new way takes most of the data administration things that needed to be done manually and perfectly in previous systems and makes them automatic.

Is the New Style of Shepherding Safe?

The first thing to remember is that the old way is not safe unless performed perfectly and perfection is not an attribute often associated with human activities. The new way attempts to remove most opportunities for losing data.

So is there a downside to the new way? There is one. The new system has been in use for only about 6 months starting with a few people originally and several hundred now. The common paths through the new system have been used enough that they work well. HOWEVER, the system is still new enough that you might accidentally come upon an uncommon path that no one has gone down before and be hit with a _bug_, sigh.

This happened to one project team in PNG last week. Some program (not sure yet which) had written an extra null character to the end of each file. This caused the new system to not merge data from two machines correctly. The data was not gone but it had disappeared from view. The good news ... with the new system data that appears to be lost is probably not --- see the next two sections on how to find your data and get it back.

What can be done to make using the new system safer? During the next few months especially do not exclusively rely on the new system. Occasionally (at least once a week?) make a File/Backup like you have always done before. Also be suspicious whenever you try new things, e.g. the first time you try to merge data from 4 people at the same time, checking to make sure the operation completed correctly.

Finding Lost Sheep

The new system can effectively have hundreds of copies of a project. After a File > Send/Receive there is at least one copy for each active day of the project for each machine in the project. So if you discover that there is some data missing from a book how do you find the correct saved copy from the potentially hundreds of copies present?

Method #1: If you used Project > Mark Point in Project History to give the copy you want a name congratulate yourself for foresight. You can use the command Project > View Project History and you can see in the left pane of the window the comment text that you entered earlier. If you are looking for data missing from the current book or chapter you can restrict the history to only show copies that changed that book or chapter by selecting an option from the Show drop down at the top of this pane.

Method #2: If you know that data is missing from a specific verse you can right click in the verse and chose "View History for Verse" to see all the copies containing changes to the current verse. This will also show you the contents of the verse in all these copies which is very helpful for other kinds of questions like "This verse used to have another translation for 'mercy' but what was it?."

Method #3: If you would like to browse through many copies use the command Tools > Compare Texts. Click Select at the top of the right pane to chose an earlier copy to compare to the current text. There are many options under the View menu for this window that you can use to determine how the changes are shown.

Getting You Sheep Back

After you have found an earlier copy of the project that has the text you want how do you get it back?

To get back one chapter or less

  • Click Tools > Compare Texts.
  • Click Select in the right hand pane and choose the earlier copy of the project you wish to restore from.
    At this point the current text of the project will be in the left pane and the older version in the right pane.
  • Select the portion of the chapter you wish to restore in the right pane and copy it with Edit > Copy.
  • Select the portion of the text you want to restore in the left pane and replace it with Edit > Paste.
  • You may also restore individual changes from the right pane by right clicking on them and selecting Undo Changed Text.

To get back one or more books

Obviously this should be done with extreme caution! You should use Project > Mark Point in Project History and supply a comment like "Before restoring GEN and EXO back to the draft level 1 copies". This would allow you to undo this operation easily at a later date (In Paratext 7.1 we plan to do this automatically).

  • Click Project > Project History.
  • Click on the copy of the project you want to restore in the left pane.
  • Click the Restore icon in the toolbar (this is a curved arrow that points left).
  • Choose the book(s) you want to restore.
  • Click OK.


If You Have a Problem with the New Sheep Folds

Please tell us as clearly as possible what happened. For Example:

In GEN 3:11 I corrected the spelling of 'gora' -> 'goro' on the afternoon of May 11 and the next day the change had disappeared".

Please don't just say "One day I typed something and the next day it was gone."

We will need a copy of your repository to see what happened. If you have access to the internet:

  • Use File > Send/Receive with Internet to place a copy of the project on the internet server.
  • In this dialog click Settings and then "Share Project".
  • Use Help > Report a Problem to send any details you have as to what data has gone missing or become incorrect during the Send/Receive process.
  • Be sure to include the number generated by "Share Project" in your problem report.

If you do not have Internet access, then you or a support person could zip up the entire project directory and email it to pt7@ubs-icap.org.

Thanks for reading this. May the Lord bless you as you shepherd your data.

Nathan Miles