From: Bill Chatfield <bill_chatfield@yahoo.com>
Date: Sun, 30 Jul 2017 23:51:23 +0000 (-0400)
Subject: Made corrections according to review comments
X-Git-Tag: V2.17~109^2
X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=refs%2Fpull%2F472%2Fhead;p=cc65

Made corrections according to review comments
---

diff --git a/doc/apple2enh.sgml b/doc/apple2enh.sgml
index 672f5d6aa..c7be9b474 100644
--- a/doc/apple2enh.sgml
+++ b/doc/apple2enh.sgml
@@ -519,9 +519,108 @@ url="ca65.html" name="assembler manual">.
 
 <sect1>Specifying file types for fopen<p>
 
-See section 
-<url url="apple2.html#ss9.4" name="Specifying file types for fopen">
-in the apple2 docoumentation.
+<descrip>
+
+  <tag>Explanation of File Types</tag>
+
+  ProDOS associates a file type and an auxiliary type with each file.
+  These type specifications are separate from the file's name, unlike
+  Windows which uses the file name's suffix (a.k.a.
+  extension) to specify the file type. For example, <tt/.exe/, 
+  <tt/.doc/, or <tt/.bat/.
+  The ProDOS low-level 
+  Machine-Language Interface (MLI) functions for creating and opening 
+  files require these types to be specified. And if they don't match
+  with the file being opened, the operation may fail.
+
+  In contrast, the ISO C function <tt/fopen()/ and the POSIX function
+  <tt/open()/ have no parameter to specify either a file type or an
+  auxiliary type. Therefore, some additional mechanism for specifying
+  the file types is needed. 
+  
+  <tag>Specifying the File Type and Auxiliary Type</tag>
+
+  There are two global variables provided that allow the file type
+  and auxiliary type to be specified before a call to <tt/fopen()/
+  or <tt/open()/. They are defined in <tt/apple2_filetype.h/:
+
+  <tscreen>
+  <verb>
+  extern unsigned char _filetype;  /* Default: PRODOS_T_BIN */
+  extern unsigned int _auxtype;    /* Default: 0            */
+  </verb>
+  </tscreen>  
+
+  The header file <tt/apple2_filetype.h/ also defines many values
+  that can be used to set these variables. It is included in
+  <tt/apple2.h/, which is in turn included in <tt/apple2enh.h/.
+  So it isn't necessary to include it directly. Just
+  include one of <tt/apple2.h/ or <tt/apple2enh.h/.
+
+  <tag>Example</tag>
+
+  A text file cannot be created with just the
+  standard C functions because they default to the binary type 
+  <tt/PRODOS_T_BIN/. The <tt/_filetype/ variable must be set to
+  <tt/PRODOS_T_TXT/ to create a text file. 
+  
+  For a text file, 
+  <tt/_auxtype/ specifies the record length. A zero record
+  length text file is referred to as a sequential text file.
+  This is equivalent to text files on 
+  other operating systems, except that the line terminator is a
+  carriage return instead of a line-feed (Linux/BSD/MacOS) or 
+  carriage return, line-feed pair (Windows).
+  
+  The "sequential" text file terminology is in contrast to a 
+  "random-access" text file which would
+  have a fixed-length, non-zero record length, so that the 
+  file position of any individual record can be calculated.
+  
+  For this example, the
+  <tt/_auxtype/ does not need to be set because it defaults to
+  the desired value, which is zero. To be more explicit, 
+  <tt/_auxtype/ can also be set to <tt/PRODOS_AUX_T_TXT_SEQ/
+  which is defined as zero.
+
+  <tscreen>
+  <verb>
+    &num;include &lt;stdio.h&gt;
+    &num;include &lt;string.h&gt;
+    &num;include &lt;errno.h&gt;
+    &num;include &lt;apple2.h&gt;
+
+    void main(void)
+    {
+        FILE *out;
+        char *name = "MY.FAVS";
+
+        /*-----------------------------*/
+
+        _filetype = PRODOS_T_TXT;
+        _auxtype  = PRODOS_AUX_T_TXT_SEQ;
+
+        /*-----------------------------*/
+
+        if ((out = fopen(name, "w")) != NULL) {
+            fputs("Jorah Mormont\r", out);
+            fputs("Brienne of Tarth\r", out);
+            fputs("Daenerys Targaryen\r", out);
+            fputs("Sandor Clegane\r", out);
+            if (fclose(out) == EOF) {
+                fprintf(stderr, "fclose failed for %s: %s", name, strerror(errno));
+            }
+        }
+        else {
+            fprintf(stderr, "fopen failed for %s: %s", name, strerror(errno));
+        }
+    }
+  </verb>
+  </tscreen>  
+
+</descrip><p>
+
+