Expand documentation on valid text files

Note: This was part of earlier work done when addressing the issue of strict parsing before it was decided that Serval should not validate files. It would still be beneficial to incorporate.

src/Serval.Client/Client.g.cs

@@ -47,9 +47,12 @@ public partial interface IDataFilesClient
         /// <param name="file">The file to upload.  Max size: 100MB</param>
         /// <param name="format">File format options:
         /// <br/>* **Text**: One translation unit (a.k.a., verse) per line
-        /// <br/>  * If there is a tab, the content before the tab is the unique identifier for the line
-        /// <br/>  * Otherwise, no tabs should be used in the file.
-        /// <br/>* **Paratext**: A complete, zipped Paratext project backup: that is, a .zip archive of files including the USFM files and "Settings.xml" file. To generate a zipped backup for a project in Paratext, navigate to "Paratext/Advanced/Backup project to file..." and follow the dialogue.</param>
+        /// <br/>  * If a line contains a tab, characters before the tab are used as a unique identifier for the line, characters after the tab are understood as the content of the verse, and if there is another tab following the verse content, characters after this second tab are assumed to be column codes like "ss" etc. for sectioning and other formatting. See this example of a tab-delimited text file:
+        /// <br/>    &gt; verse_001_005 (tab) Ὑπομνῆσαι δὲ ὑμᾶς βούλομαι , εἰδότας ὑμᾶς ἅπαξ τοῦτο
+        /// <br/>    &gt; verse_001_006	(tab) Ἀγγέλους τε τοὺς μὴ τηρήσαντας τὴν ἑαυτῶν ἀρχήν , ἀλλὰ (tab) ss
+        /// <br/>    &gt; verse_001_007 (tab) Ὡς Σόδομα καὶ Γόμορρα , καὶ αἱ περὶ αὐτὰς πόλεις (tab) ss
+        /// <br/>  * Otherwise, *no tabs* should be used in the file and a unique identifier will generated for each translation unit based on the linenumber.
+        /// <br/>* **Paratext**: A complete, zipped Paratext project</param>
         /// <param name="name">A name to help identify and distinguish the file.
         /// <br/>Recommendation: Create a multi-part name to distinguish between projects, uses, languages, etc.
         /// <br/>The name does not have to be unique.
@@ -231,9 +234,12 @@ public string BaseUrl
         /// <param name="file">The file to upload.  Max size: 100MB</param>
         /// <param name="format">File format options:
         /// <br/>* **Text**: One translation unit (a.k.a., verse) per line
-        /// <br/>  * If there is a tab, the content before the tab is the unique identifier for the line
-        /// <br/>  * Otherwise, no tabs should be used in the file.
-        /// <br/>* **Paratext**: A complete, zipped Paratext project backup: that is, a .zip archive of files including the USFM files and "Settings.xml" file. To generate a zipped backup for a project in Paratext, navigate to "Paratext/Advanced/Backup project to file..." and follow the dialogue.</param>
+        /// <br/>  * If a line contains a tab, characters before the tab are used as a unique identifier for the line, characters after the tab are understood as the content of the verse, and if there is another tab following the verse content, characters after this second tab are assumed to be column codes like "ss" etc. for sectioning and other formatting. See this example of a tab-delimited text file:
+        /// <br/>    &gt; verse_001_005 (tab) Ὑπομνῆσαι δὲ ὑμᾶς βούλομαι , εἰδότας ὑμᾶς ἅπαξ τοῦτο
+        /// <br/>    &gt; verse_001_006	(tab) Ἀγγέλους τε τοὺς μὴ τηρήσαντας τὴν ἑαυτῶν ἀρχήν , ἀλλὰ (tab) ss
+        /// <br/>    &gt; verse_001_007 (tab) Ὡς Σόδομα καὶ Γόμορρα , καὶ αἱ περὶ αὐτὰς πόλεις (tab) ss
+        /// <br/>  * Otherwise, *no tabs* should be used in the file and a unique identifier will generated for each translation unit based on the linenumber.
+        /// <br/>* **Paratext**: A complete, zipped Paratext project</param>
         /// <param name="name">A name to help identify and distinguish the file.
         /// <br/>Recommendation: Create a multi-part name to distinguish between projects, uses, languages, etc.
         /// <br/>The name does not have to be unique.
@@ -1011,13 +1017,13 @@ public partial interface ITranslationEnginesClient
         /// Get a build job
         /// </summary>
         /// <remarks>
-        /// If the `minRevision` is not defined, the current build at whatever state it is
+        /// If the `minRevision` is not defined, the current build, at whatever state it is,
         /// <br/>will be immediately returned.  If `minRevision` is defined, Serval will wait for
         /// <br/>up to 40 seconds for the engine to build to the `minRevision` specified, else
         /// <br/>will timeout.
         /// <br/>A use case is to actively query the state of the current build, where the subsequent
-        /// <br/>request sets the `minRevision` to the returned `revision` + 1.  Note: this method
-        /// <br/>should use request throttling.
+        /// <br/>request sets the `minRevision` to the returned `revision` + 1 and timeouts are handled gracefully.
+        /// <br/>Note: this method should use request throttling.
         /// </remarks>
         /// <param name="id">The translation engine id</param>
         /// <param name="buildId">The build job id</param>
@@ -1031,7 +1037,7 @@ public partial interface ITranslationEnginesClient
         /// Get the currently running build job for a translation engine
         /// </summary>
         /// <remarks>
-        /// See "Get a Build Job" for details on minimum revision.
+        /// See documentation on endpoint /translation/engines/{id}/builds/{id} - "Get a Build Job" for details on using `minRevision`.
         /// </remarks>
         /// <param name="id">The translation engine id</param>
         /// <param name="minRevision">The minimum revision</param>
@@ -2922,13 +2928,13 @@ public string BaseUrl
         /// Get a build job
         /// </summary>
         /// <remarks>
-        /// If the `minRevision` is not defined, the current build at whatever state it is
+        /// If the `minRevision` is not defined, the current build, at whatever state it is,
         /// <br/>will be immediately returned.  If `minRevision` is defined, Serval will wait for
         /// <br/>up to 40 seconds for the engine to build to the `minRevision` specified, else
         /// <br/>will timeout.
         /// <br/>A use case is to actively query the state of the current build, where the subsequent
-        /// <br/>request sets the `minRevision` to the returned `revision` + 1.  Note: this method
-        /// <br/>should use request throttling.
+        /// <br/>request sets the `minRevision` to the returned `revision` + 1 and timeouts are handled gracefully.
+        /// <br/>Note: this method should use request throttling.
         /// </remarks>
         /// <param name="id">The translation engine id</param>
         /// <param name="buildId">The build job id</param>
@@ -3020,7 +3026,7 @@ public string BaseUrl
                         if (status_ == 408)
                         {
                             string responseText_ = ( response_.Content == null ) ? string.Empty : await response_.Content.ReadAsStringAsync().ConfigureAwait(false);
-                            throw new ServalApiException("The long polling request timed out", status_, responseText_, headers_, null);
+                            throw new ServalApiException("The long polling request timed out. This is expected behavior if you\'re using long-polling with the minRevision strategy specified in the docs", status_, responseText_, headers_, null);
                         }
                         else
                         if (status_ == 503)
@@ -3053,7 +3059,7 @@ public string BaseUrl
         /// Get the currently running build job for a translation engine
         /// </summary>
         /// <remarks>
-        /// See "Get a Build Job" for details on minimum revision.
+        /// See documentation on endpoint /translation/engines/{id}/builds/{id} - "Get a Build Job" for details on using `minRevision`.
         /// </remarks>
         /// <param name="id">The translation engine id</param>
         /// <param name="minRevision">The minimum revision</param>
@@ -3146,7 +3152,7 @@ public string BaseUrl
                         if (status_ == 408)
                         {
                             string responseText_ = ( response_.Content == null ) ? string.Empty : await response_.Content.ReadAsStringAsync().ConfigureAwait(false);
-                            throw new ServalApiException("The long polling request timed out.  Did you start the build?", status_, responseText_, headers_, null);
+                            throw new ServalApiException("The long polling request timed out. This is expected behavior if you\'re using long-polling with the minRevision strategy specified in the docs", status_, responseText_, headers_, null);
                         }
                         else
                         if (status_ == 503)

src/Serval.DataFiles/Controllers/DataFilesController.cs

@@ -90,11 +90,13 @@ public async Task<ActionResult<DataFileDto>> GetAsync([NotNull] string id, Cance
     /// <param name="format">
     /// File format options:
     /// * **Text**: One translation unit (a.k.a., verse) per line
-    ///   * If there is a tab, the content before the tab is the unique identifier for the line
-    ///   * Otherwise, no tabs should be used in the file.
-    /// * **Paratext**: A complete, zipped Paratext project backup: that is, a .zip archive of files including the USFM files and "Settings.xml" file. To generate a zipped backup for a project in Paratext, navigate to "Paratext/Advanced/Backup project to file..." and follow the dialogue.
-    /// </param>
-    /// <param name="idGenerator"></param>
+    ///   * If a line contains a tab, characters before the tab are used as a unique identifier for the line, characters after the tab are understood as the content of the verse, and if there is another tab following the verse content, characters after this second tab are assumed to be column codes like "ss" etc. for sectioning and other formatting. See this example of a tab-delimited text file:
+    ///     > verse_001_005 (tab) Ὑπομνῆσαι δὲ ὑμᾶς βούλομαι , εἰδότας ὑμᾶς ἅπαξ τοῦτο
+    ///     > verse_001_006	(tab) Ἀγγέλους τε τοὺς μὴ τηρήσαντας τὴν ἑαυτῶν ἀρχήν , ἀλλὰ (tab) ss
+    ///     > verse_001_007 (tab) Ὡς Σόδομα καὶ Γόμορρα , καὶ αἱ περὶ αὐτὰς πόλεις (tab) ss
+    ///   * Otherwise, *no tabs* should be used in the file and a unique identifier will generated for each translation unit based on the linenumber.
+    /// * **Paratext**: A complete, zipped Paratext project
+    /// </param>    /// <param name="idGenerator"></param>
     /// <param name="cancellationToken"></param>
     /// <response code="201">The file was created successfully</response>
     /// <response code="400">Bad request. Is the file over 100 MB?</response>