texmf -> texmf-dist: doc

git-svn-id: svn://tug.org/texlive/trunk@29714 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 318 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/bibtexu/csfile.txt b/Master/texmf-dist/doc/bibtexu/csfile.txt
new file mode 100644
index 00000000000..9f112a466c3
--- /dev/null
+++ b/Master/texmf-dist/doc/bibtexu/csfile.txt
@@ -0,0 +1,318 @@
+******************************************************************************
+FILE: $RCSfile: csfile.txt,v $
+      $Revision: 3.71 $
+      $Date: 1996/08/18 20:41:31 $
+******************************************************************************
+
+
+An 8-bit Implementation of BibTeX 0.99 with a Very Large Capacity
+=================================================================
+
+
+Contents
+--------
+
+    1.  The Codepage and Sort Order (CS) File
+    	1.1 CS file syntax
+	1.2 Testing a CS file
+	1.3 Sharing your CS file
+
+    2.  Change Log
+
+
+
+1.  The Codepage and Sort Order (CS) File
+-----------------------------------------
+
+The Codepage and Sort definition (CS) file is used to define the 8-bit
+character set used by BibTeX and the order in which those characters should
+be sorted.  
+
+NOTE:   this file contains many 8-bit characters and may cause problems
+        if you try to display or print it on 7-bit systems (e.g. older
+        versions of Unix).
+
+
+    1.1 CS file syntax
+    ------------------
+
+    The codepage and sorting order (CS) file defines how BibTeX will treat an
+    8-bit character set, specifically which characters are to be treated as
+    letters, the upper/lower case relationships between characters, and the
+    sorting order of characters.
+  
+    The CS file may contain a number of sections, each presented in the form
+    of a TeX macro:
+  
+        \section-name{
+            <section definitions>
+        }
+  
+    Four sections are currently supported: \lowupcase, \lowercase, \uppercase
+    and \order.  The syntax of the four supported sections is summarised
+    below.
+  
+    8-bit characters may be entered naturally, but to avoid problems with
+    character set translation or corruption, they can also be entered using
+    the TeX-style portable notation for character codes, i.e. ^^XX, where XX
+    is the hexadecimal value ofthe character code.
+  
+    Reading of the sections ends when the first '}' character is reached, so
+    '}' can't be included in a section.  You can, however, use ^^7d instead.
+  
+    The percent sign ('%') is used to introduce a trailing comment - it and
+    all remaining characters on a line are ignored.  If you need to insert a
+    percent character, you can use ^^25 instead.
+  
+  
+    \lowupcase section
+  
+        The \lowupcase section of the CS file is used to define the lower
+        /upper and upper/lower case relationship of pairs of specified
+        characters.  It is only used if the relationship is symmetrical - use
+        \lowercase or \upcase if it isn't.
+    
+        The syntax of the \lowupcase section is:
+  
+            \lowupcase{
+                <LC-1> <UC-1>   % Comment begins with a percent sign
+                <LC-2> <UC-2>
+                ...
+                <LC-N> <UC-N>
+            }
+  
+        Each <LC-n> <UC-n> pair of characters defines that the upper case
+        equivalent of <LC-n> is <UC-n> *and* the lower case equivalent of
+        <UC-n> is <LC-n>.
+  
+        You cannot redefine the lower or upper case equivalent of an ASCII
+        character (code < 128), so all instances of <LC-n> and <UC-n> (i.e.
+        both sides of the relationship) must have codes > 127.
+  
+  
+   \lowercase section
+  
+        The \lowercase section of the CS file is used to define the lower
+        case equivalent of specified characters.  It should normally only be
+        used if the relationship isn't symmetrical - use \lowupcase if it is.
+  
+        The syntax of the \lowercase section is:
+  
+            \lowercase{
+                <UC-1> <LC-1>   % Comment begins with a percent sign
+                <UC-2> <LC-2>
+                ...
+                <UC-N> <LC-N>
+            }
+  
+        Each <LC-n> <UC-n> pair of characters defines that the lower case
+        equivalent of <UC-n> is <LC-n>.
+  
+        You cannot redefine the lower case equivalent of an ASCII character
+        (code < 128), so all instances of <UC-n> (i.e. the left hand side of
+        the relationship) must have codes > 127.
+  
+  
+   \uppercase section
+  
+        The \uppercase section of the CS file is used to define the upper
+        case equivalent of specified characters.  It should normally only be
+        used if the relationship isn't symmetrical - use \lowupcase if it is.
+  
+        The syntax of the \uppercase section is:
+  
+            \uppercase{
+                <LC-1> <UC-1>   % Comment begins with a percent sign
+                <LC-2> <UC-2>
+                ...
+                <LC-N> <UC-N>
+            }
+  
+        Each <LC-n> <UC-n> pair of characters defines that the upper case
+        case equivalent of <LC-n> is <UC-n>.
+  
+        You cannot redefine the upper case equivalent of an ASCII character
+        (code < 128), so all instances of <LC-n> (i.e. the left hand side of
+        the relationship) must have codes > 127.
+  
+  
+    \order section
+  
+        The \order section of the CS file is used to define the order in
+        which characters are sorted.
+  
+        The syntax of the \order section is:
+  
+            \order{
+                <char-1>                % Comment begins with a percent sign
+                <char-2> <char-3>       % whitespace between the chars
+                <char-4> - <char-5>     % a hyphen between the chars
+                <char-4> _ <char-5>     % an underscore between the chars
+                ...
+                <char-n>
+            }
+  
+        All characters on the same line are given the same sorting weight.
+  
+        The construct <char-1> <underscore> <char-2> is used to denote that
+        all characters in the range <char-1> to <char-2> should be given the
+        same sorting weight.  For example, "A _ Z" would cause all ASCII
+        upper case alphabetical characters to have the same sorting weight
+        and would be equivalent to placing all 26 characters on the same
+        line.
+  
+        The construct <char-1> <hyphen> <char-2> is used to denote that all
+        characters in the range <char-1> to <char-2> should be given an
+        ascending set of sorting weights, starting with <char-1> and ending
+        with <char-2>.  For example, "A - Z" would cause all upper case ASCII
+        alphabetical characters to be sorted in ascending order and would be
+        equivalent to placing 'A' on the first line, 'B' on the second,
+        through to 'Z' on the 26th line.
+  
+        The characters at the beginning of the order section are given a
+        lower sorting weight than characters occuring later.  When sorting
+        alphabetically, characters with the lowest weight come first.
+        
+        All characters not in the \order section (including ASCII characters)
+        are given the same very high sorting weight to ensure that they come
+        last when sorting alphabetically.
+
+
+    1.2 Testing a CS file
+    ---------------------
+
+    If you create a CS, you'll want a straightforward way of testing that
+    BibTeX is interpreting it as you expect it to.  The --debug=csf option
+    will report the results of parsing the CS file.  Specifically, BibTeX
+    will report:
+    
+        o   characters with codes > 127 that it has defined as type ALPHA
+        o   characters with upper case equivalents
+        o   characters with lower case equivalents
+        o   characters in ascending sorting order
+
+    An example of the output when processing the cp437lat.csf CS file is
+    shown below.  This output will only make sense if you are using a
+    computer that supports the IBM codepage 437.
+
+        D-CSF: c8read_csf: trying to open CS file `cp437lat.csf' ...
+        D-CSF: reading the \lowupcase section ... 
+        D-CSF: finished reading the \lowupcase section.
+        D-CSF: reading the \uppercase section ... 
+        D-CSF: finished reading the \uppercase section.
+        D-CSF: reading the \order section ... 
+        D-CSF: finished reading the \order section.
+        
+        D-CSF: 8-bit ALPHA characters
+        D-CSF: ----------------------
+        D-CSF: 80:  �  �  �  �  �  �  �  �  �  �  �  �  �  �  �  �  
+        D-CSF: 90:  �  �  �  �  �  �  �  �  .  �  �  .  .  .  .  .  
+        D-CSF: a0:  �  �  �  �  �  �  .  .  .  .  .  .  .  .  .  .  
+        D-CSF: b0:  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  
+        D-CSF: c0:  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  
+        D-CSF: d0:  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  
+        D-CSF: e0:  .  �  .  .  .  .  .  .  .  .  .  .  .  .  .  .  
+        D-CSF: f0:  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  
+        
+        D-CSF: Characters with upper case equivalents
+        D-CSF: --------------------------------------
+        D-CSF: a [61] <<< A [41]      b [62] <<< B [42]      c [63] <<< C [43]
+        D-CSF: d [64] <<< D [44]      e [65] <<< E [45]      f [66] <<< F [46]
+        D-CSF: g [67] <<< G [47]      h [68] <<< H [48]      i [69] <<< I [49]
+        D-CSF: j [6a] <<< J [4a]      k [6b] <<< K [4b]      l [6c] <<< L [4c]
+        D-CSF: m [6d] <<< M [4d]      n [6e] <<< N [4e]      o [6f] <<< O [4f]
+        D-CSF: p [70] <<< P [50]      q [71] <<< Q [51]      r [72] <<< R [52]
+        D-CSF: s [73] <<< S [53]      t [74] <<< T [54]      u [75] <<< U [55]
+        D-CSF: v [76] <<< V [56]      w [77] <<< W [57]      x [78] <<< X [58]
+        D-CSF: y [79] <<< Y [59]      z [7a] <<< Z [5a]      � [81] <<< � [9a]
+        D-CSF: � [82] <<< � [90]      � [83] <<< A [41]      � [84] <<< � [8e]
+        D-CSF: � [85] <<< A [41]      � [86] <<< � [8f]      � [87] <<< � [80]
+        D-CSF: � [88] <<< E [45]      � [89] <<< E [45]      � [8a] <<< E [45]
+        D-CSF: � [8b] <<< I [49]      � [8c] <<< I [49]      � [8d] <<< I [49]
+        D-CSF: � [91] <<< � [92]      � [93] <<< O [4f]      � [94] <<< � [99]
+        D-CSF: � [95] <<< O [4f]      � [96] <<< U [55]      � [97] <<< U [55]
+        D-CSF: � [a0] <<< A [41]      � [a1] <<< I [49]      � [a2] <<< O [4f]
+        D-CSF: � [a3] <<< U [55]      � [a4] <<< � [a5]
+        
+        D-CSF: Characters with lower case equivalents
+        D-CSF: --------------------------------------
+        D-CSF: A [41] >>> a [61]      B [42] >>> b [62]      C [43] >>> c [63]
+        D-CSF: D [44] >>> d [64]      E [45] >>> e [65]      F [46] >>> f [66]
+        D-CSF: G [47] >>> g [67]      H [48] >>> h [68]      I [49] >>> i [69]
+        D-CSF: J [4a] >>> j [6a]      K [4b] >>> k [6b]      L [4c] >>> l [6c]
+        D-CSF: M [4d] >>> m [6d]      N [4e] >>> n [6e]      O [4f] >>> o [6f]
+        D-CSF: P [50] >>> p [70]      Q [51] >>> q [71]      R [52] >>> r [72]
+        D-CSF: S [53] >>> s [73]      T [54] >>> t [74]      U [55] >>> u [75]
+        D-CSF: V [56] >>> v [76]      W [57] >>> w [77]      X [58] >>> x [78]
+        D-CSF: Y [59] >>> y [79]      Z [5a] >>> z [7a]      � [80] >>> � [87]
+        D-CSF: � [8e] >>> � [84]      � [8f] >>> � [86]      � [90] >>> � [82]
+        D-CSF: � [92] >>> � [91]      � [99] >>> � [94]      � [9a] >>> � [81]
+        D-CSF: � [a5] >>> � [a4]
+        
+        D-CSF: Characters in sorting order
+        D-CSF: ---------------------------
+        D-CSF: 00:  0 [30] 
+        D-CSF: 01:  1 [31] 
+        D-CSF: 02:  2 [32] 
+        D-CSF: 03:  3 [33] 
+        D-CSF: 04:  4 [34] 
+        D-CSF: 05:  5 [35] 
+        D-CSF: 06:  6 [36] 
+        D-CSF: 07:  7 [37] 
+        D-CSF: 08:  8 [38] 
+        D-CSF: 09:  9 [39] 
+        D-CSF: 0a:  A [41] a [61] � [83] � [84] � [85] � [86] � [8e] � [8f] � [a0] 
+        D-CSF: 0b:  � [91] � [92] 
+        D-CSF: 0c:  B [42] b [62] 
+        D-CSF: 0d:  C [43] c [63] � [80] � [87] 
+        D-CSF: 0e:  D [44] d [64] 
+        D-CSF: 0f:  E [45] e [65] � [82] � [88] � [89] � [8a] � [90] 
+        D-CSF: 10:  F [46] f [66] 
+        D-CSF: 11:  G [47] g [67] 
+        D-CSF: 12:  H [48] h [68] 
+        D-CSF: 13:  I [49] i [69] � [8b] � [8c] � [8d] � [a1] 
+        D-CSF: 14:  J [4a] j [6a] 
+        D-CSF: 15:  K [4b] k [6b] 
+        D-CSF: 16:  L [4c] l [6c] 
+        D-CSF: 17:  M [4d] m [6d] 
+        D-CSF: 18:  N [4e] n [6e] 
+        D-CSF: 19:  � [a4] � [a5] 
+        D-CSF: 1a:  O [4f] o [6f] � [93] � [94] � [95] � [99] � [a2] 
+        D-CSF: 1b:  P [50] p [70] 
+        D-CSF: 1c:  Q [51] q [71] 
+        D-CSF: 1d:  R [52] r [72] 
+        D-CSF: 1e:  S [53] s [73] 
+        D-CSF: 1f:  � [e1] 
+        D-CSF: 20:  T [54] t [74] 
+        D-CSF: 21:  U [55] u [75] � [81] � [96] � [97] � [9a] � [a3] 
+        D-CSF: 22:  V [56] v [76] 
+        D-CSF: 23:  W [57] w [77] 
+        D-CSF: 24:  X [58] x [78] 
+        D-CSF: 25:  Y [59] y [79] 
+        D-CSF: 26:  Z [5a] z [7a] 
+        D-CSF: (All other characters are sorted equally after any of the above.)
+
+    
+    1.3 Sharing your CS file
+    ------------------------
+
+    Although we have provided a limited number of CS files, we hope that
+    other will soon produce different examples for other character sets and
+    national sorting orders.  We will also be happy to accept corrections to
+    the example files supplied.
+
+    If you'd like to contribute a CS file, please send it to one of the
+    authors or upload it to one of the CTAN FTP archives.  If you e-mail a
+    copy please ZIP and encode (UU/MIME) it so that we can be confident that
+    the file has not become corrupted in transit.
+
+
+
+2.  Change Log
+--------------
+
+$Log: csfile.txt,v $
+# Revision 3.71  1996/08/18  20:41:31  kempson
+# Placed under RCS control.
+#
+******************************** END OF FILE *******************************