Merge branch 'feature/163-update-save-snippet-info-help' into develop

Fixes #163

Author: delphidabbler

Docs/Design/FileFormats/saved.html

@@ -62,9 +62,27 @@ <h2>
 </ol>
 
 <p>
-  In the first case the snippet is always saved in rich text format.
+  In the first case the snippet information can be saved as one of the following file types:
 </p>
 
+<ul>
+  <li>
+    Plain text.
+  </li>
+  <li>
+    HTML 5 files.
+  </li>
+  <li>
+    XHTML files.
+  </li>
+  <li>
+    Rich text files.
+  </li>
+  <li>
+    Markdown files.
+  </li>
+</ul>
+
 <p>
   In the second two cases the following file types can be chosen by the user:
 </p>
@@ -88,7 +106,7 @@ <h2>
 </ul>
 
 <p>
-  There is no specific file format for these files, except that HTML 5, XHTML and RTF
+  There is no specific file format for these files, except that HTML 5, XHTML, RTF and Markdown
   files conform to published specifications.
 </p>
 
@@ -97,11 +115,7 @@ <h2>
 </h2>
 
 <p>
-  In the first case the RTF is always saved in ASCII format.
-</p>
-
-<p>
-  In the 2nd and 3rd cases the encodings used depend on the file type and user choice. Different file
+  The available encodings used depend on the file type and user choice. Different file
   types have different encoding choices, as follows:
 </p>
 
@@ -164,7 +178,7 @@ <h2>
   <dd>
     <ul class="squashed">
       <li>
-        ANSI (system default code page). ASCII format is actually used.
+        ASCII [for Snippet Information] or ANSI [otherwise]. Regardless of naming, ASCII format is always used.
       </li>
     </ul>
   </dd>

Src/Help/HTML/dlg_saveinfo.htm

@@ -28,21 +28,93 @@ <h1>
     </h1>
     <p>
         This dialogue box is displayed when the <em>File | Save Snippet
-        Information</em> menu option is clicked. It is used to specify the
-        name of the file into which information about the currently selected
-        snippet is to be saved.
+        Information</em> menu option is clicked. It is used to specify the file
+        name, file type and encoding information for the snippet information 
+        that is to be saved.
     </p>
     <p>
-        The saved snippet information is written in rich text format.
+        The dialogue is a standard Windows save dialogue box with a few added
+        options.
     </p>
     <p>
-        This dialogue is a standard Windows save dialogue box. You specify the
-         name and folder for the file in the usual way.
+        You specify the name and folder for the file where the snippet information
+        is to be written in in the usual way.
     </p>
     <p>
-        Use the <em>Save</em> button to write the file to disk or press
+        Use the <em>Save as type</em> drop down list to specify the type of file
+        to be saved. Options are:
+    </p>
+    <ul>
+        <li>Plain text.</li>
+        <li>HTML</li>
+        <li>XHTML</li>
+        <li>Rich text format</li>
+        <li>Markdown</li>
+    </ul>
+    <p>
+        The HTML 5 and XHTML options are very similar and differ only in the
+        type of HTML that is written. For either type an embedded CSS style
+        sheet is used to style the document.
+    </p>
+    <p>
+        When any of the HTML 5, XHTML or rich text file types are selected source
+        code embedded in the snippet information will be syntax highlighted if
+        the <em>Use syntax highlighting</em> check box is checked.
+    </p>
+    <p>
+        The output file encoding can be be specified in the <em>File Encoding</em>
+        drop down list. Options vary depending on the file type. Some file types
+        support only a single encoding. The encodings are:
+    </p>
+    <ul>
+        <li>
+            <em>ANSI (Default)</em> &ndash; the system default ANSI encoding.
+            Available as an option for plain text and Markdown file formats.
+        </li>
+        <li>
+            <em>UTF-8</em> &ndash; UTF-8 encoding, with BOM<sup>&dagger;</sup>.
+            Available as an option for plain text and Markdown file formats and
+            as the only encoding available for HTML 5 and XHTML file formats.
+        </li>
+        <li>
+            <em>Unicode (Little Endian)</em> &ndash; UTF-16 LE encoding, with
+            BOM<sup>&dagger;</sup>. Available as an option for plain text files and Markdown
+            file formats.
+        </li>
+        <li>
+            <em>Unicode (Big Endian)</em> &ndash; UTF-16 BE encoding, with
+            BOM<sup>&dagger;</sup>. Available as an option for plain text files and Markdown
+            file formats.
+        </li>
+        <li>
+            <em>ASCII</em> &ndash; The only encoding available for the rich text file.
+        </li>
+    </ul>
+    <p>
+        The output can be previewed by clicking the <em>Preview</em> button. This
+        displays the snippet information in a dialogue box, formatted according to your
+        selections. Text in the preview can be selected and copied to the
+        clipboard if required.
+    </p>
+    <p>
+        Use the <em>Save</em> button to write the snippet information to disk or choose
         <em>Cancel</em> to abort.
     </p>
+    <p>
+        <strong class="warning">Warning:</strong> When plain text or Markdown formatted
+        snippet information is written in ANSI format it is possibe that the information
+        contains characters that can't be represented in the system default ANSI encoding.
+        If this happens a warning
+        dialogue box is displayed whenever the snippet information is written to file
+        or is previewed.
+    </p>
+    <h3>
+        Footnote
+    </h3>
+    <p>
+        &dagger; BOM = Byte Order Mark or Preamble: a sequence of bytes at the
+        start of a text file that identifies its encoding.
+    </p>
 </body>
 
 </html>