Read/write example in temporary directory

doc/body.autodoc

@@ -436,7 +436,7 @@ storage options for elements of an extension field can in be used.
   $a_0+a_1x+a_2x^2+\ldots +a_{m-1}x^{m-1}$ as
   digits of a $p$-ary integer $(a_{m-1}a_{m-2}\ldots a_2a_1)_p$. 
   (**this is currently not implemented**)
-	
+        
 @Subsection Matrix storage format
 
 There are two recommended storage formats.
@@ -593,7 +593,7 @@ i     j     element[i,j]
 @EndCode
 @InsertCode MMXFormatLineB
 
-* `type=complex`:	
+* `type=complex`:       
 @BeginCode  MMXFormatLineC
 i     j     a[i,j]     b[i,j]
 @EndCode
@@ -649,7 +649,7 @@ is specified explicitly, this matrix would work with any
 prime field.
 
 @BeginCode SampleFileA
-%%MatrixMarket matrix coordinate integer general		
+%%MatrixMarket matrix coordinate integer general                
 % Field: GF(7)
 % 5-qubit code generator matrix / normal storage with intercalated cols
 5 10 20
@@ -679,7 +679,7 @@ prime field.
 This same matrix is stored in the file `matrices/n5k1A.mtx`.  This is
 how the matrix can be read and distance calculated:
 @BeginExample
-	filedir:=DirectoriesPackageLibrary("QDistRnd","matrices");;
+        filedir:=DirectoriesPackageLibrary("QDistRnd","matrices");;
     lis:=ReadMTXE(Filename(filedir,"n5k1A.mtx" ));;
     Print("field ",lis[1],"\n");
 #! field GF(7)

examples/examples.g

@@ -1,12 +1,14 @@
 #! @Chapter Examples
 #! @Section The 5-qubit code
 
-#! Generate the matrix of the 5-qubit code over GF(3) with the stabilizer group
+#! In this example, we generate the matrix of the 5-qubit code over GF(3) with 
+#! the stabilizer group
 #! generated by cyclic shifts of the operator $X_0Z_1 \bar Z_2 \bar
 #! X_3$ which corresponds to the polynomial $h(x)=1+x^3-x^5-x^6$
 #! (a factor $X_i^a$ corresponds to a monomial $a x^{2i}$, and a
 #! factor $Z_i^b$ to a monomial $b x^{2i+1}$),  
-#! calculate the distance, and save into the file.
+#! calculate the distance, save into a file using the function `WriteMTXE()`, and read the file back in 
+#! using the function `ReadMTXE()`. 
 #! @BeginExample
 q:=3;; F:=GF(q);; 
 x:=Indeterminate(F,"x");; poly:=One(F)*(1+x^3-x^5-x^6);;
@@ -19,14 +21,39 @@ Display(mat);
 #!  . 2 2 . . . 1 . . 1
 d:=DistRandStab(mat,100,1,0 : field:=F,maxav:=20/n);
 #! 3
-WriteMTXE("matrices/n5_q3_complex.mtx",3,mat,
+tmp_file_name:=Filename(DirectoryTemporary(),"n5_q3_complex.mtx");;
+WriteMTXE(tmp_file_name,3,mat,
         "% The 5-qubit code [[5,1,3]]_3",
         "% Generated from h(x)=1+x^3-x^5-x^6",
-        "% Example from the QDistRnd GAP package"   : field:=F);
-#! File matrices/n5_q3_complex.mtx was created
+        "% Example from the QDistRnd GAP package"   : field:=F);;
+lis:=ReadMTXE(tmp_file_name);;  # Filename(filedir,"n5_q3_complex.mtx")
+lis[1]; # the field 
+#! GF(3)
+lis[2]; # converted to `pair=1`
+#! 1
+Display(lis[3]);
+#!  1 . . 1 . 2 2 . . .
+#!  . . 1 . . 1 . 2 2 .
+#!  2 . . . 1 . . 1 . 2
+#!  . 2 2 . . . 1 . . 1
 #! @EndExample
-
-#! Here is the contents of the resulting file which also illustrates
+#! The function `WriteMTXE()` takes several arguments which specify the details of the output file format
+#! and the optional comments, see Section <Ref Sect="Section_IOFunctions"/> for the details.
+#! These ensure that all information about the code is written into the file, so that for 
+#! reading with the function `ReadMTXE()` only the file name is needed.
+#! Output is a list: `[field,pair,matrix,(list of comments)]`, where the `pair` parameter describes 
+#! the ordering of columns in the matrix, see  <Ref Chap="Chapter_FileFormat"/>.  
+#! Notice that a `pair=2` or `pair=3` matrix is always converted to `pair=1`, i.e., with $2n$
+#! intercalated columns $(a_1,b_1,a_2,b_2,\ldots)$. 
+#! The remaining portion is the list of comments.  Notice that the 1st
+#! and the last comment lines have been added automatically.
+#! @BeginLog
+#! gap> lis[4];
+#! [ "% Field: GF(3)", "% The 5-qubit code [[5,1,3]]_3",
+#!   "% Generated from h(x)=1+x^3-x^5-x^6",
+#!   "% Example from the QDistRnd GAP package", "% Values Z(3) are given" ]
+#! @EndLog
+#! Here is the contents of the created file which illustrates
 #! the `coordinate complex` data format.  Here a pair $(a_{i,j},b_{i,j})$
 #! in row $i$ and column $j$ is written as a row of 4 integers, "$i$ $j$ $a_{i,j}$
 #! $b_{i,j}$", e.g., "1 2 0 1" 
@@ -58,33 +85,6 @@ WriteMTXE("matrices/n5_q3_complex.mtx",3,mat,
 #! 4 5 0 1
 #! @EndLog
 
-#! And now let us read the matrix back from the file using the function `ReadMTXE`.   In the simplest
-#! case, only the file name is needed.
-#! Output is a list: `[field,pair,matrix,(list of comments)]`, where the `pair` parameter describes 
-#! the ordering of columns in the matrix, see  <Ref Chap="Chapter_FileFormat"/>.  
-#! Notice that a `pair=2` or `pair=3` matrix is always converted to `pair=1`, i.e., with $2n$
-#! intercalated columns $(a_1,b_1,a_2,b_2,\ldots)$. 
-#! @BeginExample
-lis:=ReadMTXE("matrices/n5_q3_complex.mtx");;  
-lis[1]; # the field 
-#! GF(3)
-lis[2]; # converted to `pair=1`
-#! 1
-Display(lis[3]);
-#!  1 . . 1 . 2 2 . . .
-#!  . . 1 . . 1 . 2 2 .
-#!  2 . . . 1 . . 1 . 2
-#!  . 2 2 . . . 1 . . 1
-#! @EndExample
-#! The remaining portion is the list of comments.  Notice that the 1st
-#! and the last comment lines have been added automatically.
-#! @BeginLog
-#! gap> lis[4];
-#! [ "% Field: GF(3)", "% The 5-qubit code [[5,1,3]]_3",
-#!   "% Generated from h(x)=1+x^3-x^5-x^6",
-#!   "% Example from the QDistRnd GAP package", "% Values Z(3) are given" ]
-#! @EndLog
-
 #! @Section Hyperbolic codes from a file
 
 #! Here we read two CSS matrices from two different files which