home *** CD-ROM | disk | FTP | other *** search
/ Mega Top 1 / os2_top1.zip / os2_top1 / APPS / TEKST / DVISP02C / EMTEX / DOC / DVISPREP.DOC
Encoding:
Text File  |  1994-06-14  |  13.9 KB  |  443 lines
  1. ==============================================================================
  2. dvisprep 0.2c                                                      11-Jun-1994
  3. ==============================================================================
  4.  
  5.  
  6. Table of Contents
  7. =================
  8.  
  9. 1    Introduction
  10. 2    Running dvisprep
  11. 3    Parameter files
  12. 3.1    Lists
  13. 3.2    Numbers
  14. 3.3    Symbols
  15. 3.4    Comments
  16. 3.5    Types of lists
  17. 3.6    Syntax and semantics for the different types of lists
  18. 3.7    Predefined table names
  19. 3.8    Predefined symbols
  20. 4    How dvispell works
  21. 5    Supplementing plain.dsi
  22. 5.1    Hints
  23.  
  24.  
  25. 1 Introduction
  26. ==============
  27.  
  28. dvisprep compiles a dvispell parameter file into binary format, to be
  29. used by dvispell.
  30.  
  31.  
  32. 2 Running dvisprep
  33. ==================
  34.  
  35.     dvisprep [-q] <txt_file> [<bin_file>]
  36.  
  37. <txt_file> is the input file.  There is no default extension.  If you
  38. type `-' for <txt_file>, input is read from standard input.  In this
  39. case, <bin_file> must be specified.
  40.  
  41. <bin_file> is the binary output file.  If <bin_file> is not specified,
  42. the name of <txt_file> is used, with the extension replaced by `.dsb'.
  43.  
  44. The -q option disables the logo.
  45.  
  46. There are no default directories.  It is recommended to put dvispell
  47. parameter files (in both text and binary formats) into directory
  48. \emtex\data.
  49.  
  50.  
  51. 3 Parameter files
  52. =================
  53.  
  54.  
  55. 3.1 Lists
  56. ---------
  57.  
  58. LISP notation is used for declaring tables.  The first element of a
  59. list is the list type.  For some table types, the second element of a
  60. list is the table name.
  61.  
  62. A list consists of a left parenthesis, the elements (which must be
  63. separated by blanks or new line characters) and a right parenthesis.
  64. The elements can be numbers, symbols or lists.  Here is an example of
  65. a list:
  66.  
  67.     (list-type <list name> (third element consisting of 6 elements)
  68.         another_table 1 "ff `a)     % a comment
  69.  
  70. This list contains the following elements:
  71.  
  72. list-type
  73.  
  74.     symbol, same as <list-type>
  75.  
  76. <list name>
  77.  
  78.     symbol
  79.  
  80. (third ... elements)
  81.  
  82.     list containing 6 elements
  83.  
  84. another_table
  85.  
  86.     symbol
  87.  
  88. 1
  89.  
  90.     number
  91.  
  92. "ff
  93.  
  94.     number
  95.  
  96. `a
  97.  
  98.     number
  99.  
  100.  
  101. 3.2 Numbers
  102. -----------
  103.  
  104. You can use the following notations for numbers (the syntax is similar
  105. to that used by TeX):
  106.  
  107. `z
  108.  
  109.     code of character z.  For portability of the parameter file,
  110.     this should be used only for letters, digits and a subset of
  111.     punctuation common to most codes (ASCII, EBCDIC)
  112.  
  113. "7a
  114.  
  115.     hexadecimal number
  116.  
  117. '172
  118.  
  119.     octal number
  120.  
  121. 122
  122.  
  123.     decimal number
  124.  
  125. All the examples above specify the same code.  Numbers must be in the
  126. range 0 through 255.
  127.  
  128.  
  129. 3.3 Symbols
  130. -----------
  131.  
  132. A symbol is a sequence of characters.  Symbols are just names of
  133. objects like tables and characters.  You should always start a symbol
  134. with a letter.  A symbol ends at the next new line character, blank or
  135. closing parenthesis.  You can enclose a symbol in <angle brackets>.
  136. This is required if the name contains a blank or a parenthesis.
  137. dvisprep and dvispell display symbols by enclosing them in
  138. <angle brackets>.  Examples of symbols:
  139.  
  140.     zero  umlaut-a  sharp_s  x  <The letter X>  digit-6
  141.  
  142.  
  143. 3.4 Comments
  144. ------------
  145.  
  146. The parameter file may contain comments which are ignored by dvisprep.
  147. Comments are started with `%' and end at the next new line character.
  148. A `%' preceded by a ` does not start a comment.  Empty lines are also
  149. ignored by dvisprep.
  150.  
  151.  
  152. 3.5 Types of lists
  153. ------------------
  154.  
  155. There are the following table types:
  156.  
  157. include
  158.  
  159.     inserts files (this is not a table, it's a directive which
  160.     immediately takes effect)
  161.  
  162. output
  163.  
  164.     specifies how to print a character given its symbolic name.  The
  165.     output table to be used can be set by the -o command line option
  166.     of dvispell
  167.  
  168. layout
  169.  
  170.     specifies how to convert character codes found in the DVI file
  171.     into symbols.  The layout table is chosen depending on the coding
  172.     scheme of the current font
  173.  
  174. font
  175.  
  176.     specifies how to convert character codes found in the DVI file
  177.     into symbols.  The layout table is chosen depending on the name of
  178.     the current font.  If both a layout table and a font table matches
  179.     the current font, the font table takes precedence in order to
  180.     implement exceptions
  181.  
  182. conversion
  183.  
  184.     specifies how to convert sequences of symbols into other sequences
  185.     of symbols.  For instance, this is used for converting an accent
  186.     code followed by a character code into an accented character
  187.     or for converting a ligature into separate characters.  The
  188.     conversion table to be used can be set by the -c command line
  189.     option of dvispell
  190.  
  191. letters
  192.  
  193.     specifies what characters are letters.  This is used for the -l
  194.     command line option of dvispell
  195.  
  196.  
  197. 3.6 Syntax and semantics for the different types of lists
  198. ---------------------------------------------------------
  199.  
  200. (include <FILENAME1> ...)
  201.  
  202.     Inserts the text files named in the list.  After reading the
  203.     files, processing is continued after the (include) list.  Example:
  204.  
  205.         (include file1.dsi file2.dsi)
  206.  
  207.     The files inserted by (include) can in turn insert files; up to 8
  208.     levels of nested files are supported.
  209.  
  210. (output <TABLENAME> ENTRY1 ENTRY2 ...)
  211.  
  212.     The second element, <TABLENAME>, of an output table is the name of
  213.     the output table.  There are two types of entries:
  214.  
  215.     symbol
  216.  
  217.         the output table having this name is copied into the current
  218.         output table
  219.  
  220.     list
  221.  
  222.         tells dvispell how to print a character.  The first element
  223.         is the symbolic name of the character.  If there is no second
  224.         element, the character will be discarded (if -u is given on
  225.         the dvispell command line) or its symbolic name is printed (if
  226.         -u is not given on the dvispell command line).  If there is a
  227.         second element, it must be a number (which is the character
  228.         code to be printed) or a list of numbers (which are the
  229.         character codes to be printed).  If there are two or more
  230.         entries for one symbol, the last one takes precedence
  231.  
  232. (layout <TABLENAME> ENTRY1 ENTRY2 ...)
  233.  
  234.     The second element, <TABLENAME>, of a layout table is the name
  235.     of the layout table.  If the coding scheme of a TFM file matches
  236.     the name of a layout table, that layout table will be used for
  237.     characters of that font (unless the font name matches a font table
  238.     entry).  There are two types of entries:
  239.  
  240.     symbol
  241.  
  242.         the layout table having this name is copied into the current
  243.         layout table
  244.  
  245.     list
  246.  
  247.         tells dvispell how to convert a character code into a symbol.
  248.         The first element is a number, the character code.  The second
  249.         element is a symbol (the symbolic name of the character) or a
  250.         list of symbols (that sequence of symbolic names will be used
  251.         for the character code).  If there are two or more entries for
  252.         one character code, the last one takes precedence
  253.  
  254. (font FONTS ENTRY1 ENTRY2 ...)
  255.  
  256.     The second element, FONTS, is either a symbol (the font name) or
  257.     a list of symbols (the font names).  If a font name matches the
  258.     symbol or one of the symbols, respectively, the entries of this
  259.     table are used for converting character codes to symbols.  A
  260.     font table contains the same sort of entries as a layout table.
  261.     Usually, a font table just copies a layout table by specifying
  262.     the name of a layout table.  Fonts which don't match their coding
  263.     scheme, like the Computer Modern text italic fonts (which contain
  264.     \pounds instead of a dollar sign in position "24), should be put
  265.     into a font table to override the layout table.
  266.  
  267. (conversion <TABLENAME> ENTRY1 ENTRY2 ...)
  268.  
  269.     The second element, <TABLENAME> of a conversion table is the name
  270.     of the conversion table.  The name of a conversion table is used
  271.     for copying the conversion table into other conversion tables and
  272.     for specifying a conversion table on the dvispell command line
  273.     (-c).  There are two types of entries:
  274.  
  275.     symbol
  276.  
  277.         the conversion table having this name is copied into the
  278.         current conversion table
  279.  
  280.     list
  281.  
  282.         defines replacement symbols for sequences of symbols.  The
  283.         first element is a symbol or a list of symbols.  This sequence
  284.         (of one or more symbolic names) is converted into the sequence
  285.         of symbolic names given by the second element, which is a
  286.         symbol or a list of symbols.  If there is no second element,
  287.         the sequence given by the first element will be discarded if
  288.         encountered.  If there are two or more entries for one symbol
  289.         or sequence of symbols, the last one takes precedence
  290.  
  291. (letters LETTER1 LETTER2 ...)
  292.  
  293.     The elements of the letters table, the symbolic names of
  294.     characters, are appended to the set of letters.  The set of
  295.     letters is used for implementing the -l command line option of
  296.     dvispell.
  297.  
  298.  
  299. 3.7 Predefined table names
  300. --------------------------
  301.  
  302. If the -o command line option of dvispell is not used, the output
  303. table named DEFAULT will be used.
  304.  
  305. If the -c command line option of dvispell is not used, the conversion
  306. table named DEFAULT will be used.
  307.  
  308.  
  309. 3.8 Predefined symbols
  310. ----------------------
  311.  
  312. Some special symbols are generated for special events encountered in
  313. DVI files:
  314.  
  315. START
  316.  
  317.     This symbol is generated at the beginning of the DVI file, before
  318.     any other character
  319.  
  320. END
  321.  
  322.     This symbol is generated at the end of the DVI file, after the
  323.     last character
  324.  
  325. WORDSPACE
  326.  
  327.     This symbol is generated between words
  328.  
  329. NEWLINE
  330.  
  331.     This symbol is generated at the beginning of each new line
  332.  
  333. NEWPAGE
  334.  
  335.     This symbol is generated at the end of each page
  336.  
  337. NONLETTER
  338.  
  339.     This symbol is generated instead of a symbolic name if the -l
  340.     command line option of dvispell has been specified and the symbol
  341.     to be printed is not in the set of letters defined by the letter
  342.     lists.  After replacing the symbol by NONLETTER, conversions
  343.     are applied again to be able to convert NONLETTER to something
  344.     different
  345.  
  346.  
  347. 4 How dvispell works
  348. ====================
  349.  
  350. dvispell converts the characters found in the DVI file into symbolic
  351. names using the layout and font tables.  Symbols are also created for
  352. line breaks, page breaks, word spaces etc.  The resulting sequence
  353. of symbols is converted into another sequence of symbols, using the
  354. active conversion table.  Starting with the first symbol of the
  355. sequence, the LONGEST matching conversion table entry is sought.  The
  356. matching symbols are replaced by the associated replacement symbols
  357. defined in the conversion table.  After inserting the new symbols,
  358. searching for a match restarts at the first new symbol.  If no match
  359. is found for the current symbol, dvispell moves to the next symbol,
  360. until the end of the sequence is reached.  If symbols have been
  361. replaced, dvispell converts the new sequence in another sequence,
  362. using the same algorithm, continuing until no symbols are replaced
  363. in a pass over the sequence.  If the -l command line option has been
  364. specified, all the symbols in the resulting sequence which are not
  365. in the set of letters, are replaced by NONLETTER and the conversion
  366. algorithm starts over again.  The resulting sequence is printed using
  367. the active output table.
  368.  
  369. Please note a subtle feature: matches involving symbols to the left of
  370. the current symbols are found in the next pass.  Example:
  371.  
  372.     (b (c d))
  373.     (c e)
  374.     ((a c) x)
  375.     ((a e) y)
  376.  
  377. The sequence of symbols `a b' is not converted into `x d', as might be
  378. expected:
  379.  
  380.     1st pass:  a b   -> a c d -> a e d
  381.                  ^        ^               (^ is below first symbol of match)
  382.     2nd pass:  a e d -> y d
  383.                ^                          (^ is below first symbol of match)
  384.     3rd pass:  a e d -> y d               (last pass because there's no match)
  385.  
  386. Of course, dvispell doesn't exactly work as outlined here: dvispell
  387. performs all the conversions in one pass, that is, you get output
  388. before dvispell has read the entire DVI file.
  389.  
  390.  
  391. 5 Supplementing plain.dsi
  392. =========================
  393.  
  394. Adding accented characters (and other objects) to plain.dsi consists
  395. of 5 steps for each character:
  396.  
  397. 1.  Choose a descriptive name for the character
  398.  
  399. 2.  Add the character to the appropriate output table(s)
  400.  
  401. 3.  If the character is a letter, add the name to the letters list.
  402.  
  403. 4.  Add symbolic names for DVI codes into the layout tables if the
  404.     codes from which your character is made up are not yet defined.
  405.  
  406. 5.  Add the character to a conversion table.  You should create a new
  407.     conversion table for your definitions.  That table can be inserted
  408.     into an existing table by putting the name of your table into an
  409.     existing table.
  410.  
  411.  
  412. 5.1 Hints
  413. ---------
  414.  
  415. Instead of modifying plain.dsi, you should create a new file, which
  416. includes plain.dsi (see polish.dsi).
  417.  
  418. If a character is available both in code pages 437 and 850, add the
  419. character to table pc437.  If a character exists only in code page
  420. 850, add the character to table pc850.  This works because table pc850
  421. copies table pc437.  If a character exists only in code page 437, add
  422. the character to table pc437 and add
  423.  
  424.     (name)
  425.  
  426. to table pc850 remove the character from table pc850.  (name) must
  427. be inserted AFTER the entry copying the pc437 table to override the
  428. copied entry.
  429.  
  430. Avoid infinite loops in conversions.  dvispell doesn't detect infinite
  431. loop.
  432.  
  433. Do not use NONLETTER in the replacement sequence of a conversion.
  434. You'd get an infinite loop.
  435.  
  436. Avoid long replacement sequences as the algorithm used by dvispell may
  437. fail in situations requiring lots of `passes' as outlined above if
  438. matches propagate too much to the left, that is, a replacement causes
  439. a match to the left of the current symbol resulting in a replacement
  440. which again causes a match to the left of that replacement and so on.
  441.  
  442.                   -------- End of DVISPREP.DOC -------------
  443.