home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / utility / rtfgen.zip / RTFGEN.DOC < prev    next >
Text File  |  1992-02-23  |  17KB  |  595 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                                      February 22, 1992
  9.  
  10.                                      RTFGEN
  11.  
  12.                  An ASCII to Rich Text Format Conversion Program
  13.                                    Version 1.0
  14.  
  15.  
  16.         OVERVIEW
  17.  
  18.         Normally, to create a help file with the Windows help compiler, 
  19.         you must first write a help topic file using a Rich Text Format 
  20.         (RTF) word processor.  For many, there are two problems here:
  21.  
  22.           1. RTF word processors are expensive.
  23.           2. Learning to use a new word processor is a nuisance and not
  24.              very productive.
  25.  
  26.         RTFGEN solves both these problems by allowing you to use your 
  27.         favorite ASCII text editor to produce RTF formatted files 
  28.         acceptable to the help compiler.
  29.  
  30.  
  31.         STEPS FOR BUILDING A HELP FILE
  32.  
  33.         The steps required to create a Windows help file using RTFGEN 
  34.         are:
  35.  
  36.           1. Using an ASCII editor, create one or more input text files.  
  37.              The layout of the input files will be discussed later.
  38.           2. Use RTFGEN to convert these files to RTF files.
  39.           3. Create a Help Project File (.HPJ) for input to the help 
  40.              compiler.  This file should reference the RTF files.
  41.           4. Run the help compiler to make the help file.
  42.  
  43.         Steps 3 and 4 are described in the help compiler documentation.  
  44.         This documentation deals with the first two steps only.
  45.  
  46.         Once the ASCII files have been written,  RTFGEN is used to 
  47.         convert them to suitable RTF format.  The file, HEADING, is used 
  48.         in constructing the RTF file and must be present on the default 
  49.         drive.  From the DOS prompt:
  50.  
  51.           RTFGEN  [Infile [Outfile]]
  52.  
  53.         The optional filenames specify the names of the ASCII input file 
  54.         and the RTF file to be generated.  If no extensions are given, 
  55.          .RTF is used by default for the output file.  If the output 
  56.         filename is missing from the command line, an RTF file will be 
  57.         created using the same name as the source file.  When neither 
  58.         filename is specified, names will be requested once execution 
  59.         starts.
  60.  
  61.  
  62.                                    1
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.           RTFGEN MYHELP
  76.  
  77.         will cause RTFGEN to look for a source file, MYHELP, and create 
  78.         an object file, MYHELP.RTF.
  79.  
  80.  
  81.         GENERAL EDITING CONSIDERATIONS
  82.  
  83.         Almost any ASCII editor may be used.  I use Borland's TURBO or 
  84.         TPW.  It's probably best to turn off options like 'optimal fill' 
  85.         which can leave invisible and possibly unknown tab characters in 
  86.         the document.  
  87.  
  88.         The use of tabs is required to obtain column allignment with 
  89.         proportional fonts.  Either the tab character or the RTF command, 
  90.         \tab, may be used with the same effect.
  91.  
  92.         Here are the default conditions use by RTFGEN:
  93.  
  94.              Helv, 10 point font.
  95.  
  96.              Paragraphs are left justified.  The first line is not 
  97.              indented.
  98.  
  99.              Paragraph indentation is set by indentation of the first 
  100.              line of the paragraph.
  101.  
  102.              Tabs are spaced every 720 twips (about 6 default 
  103.              characters).
  104.  
  105.         Any of these defaults may be changed globally for the whole 
  106.         document or locally at the topic, paragraph, or even character 
  107.         level.
  108.  
  109.         RTFGEN and/or the RTF language have special use for the following 
  110.         characters:
  111.  
  112.           `    (grave accent) Used to mark end of paragraphs.
  113.           [,]  Used to mark jumps and definitions.
  114.           {,}  Used to mark areas where font characteristics will change.
  115.           \    Used as a command start character.
  116.  
  117.         When these characters are to be used in the text, they should be 
  118.         preceded by a '\'.  Thus, '\[' will cause the left bracket to be 
  119.         inserted in text and '\\' will result in a single backslash being 
  120.         inserted in text.
  121.  
  122.         (*...*) may be used to insert comments within the text.     
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                                    2
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.         ASCII INPUT FILE LAYOUT
  141.  
  142.         The input file for RTFGEN should have the following sections:
  143.  
  144.           1. An optional document header.
  145.           2. The command, \docstart, to mark the start of the document.
  146.           3. One or more topics consisting of:
  147.                a. A topic header.
  148.                b. A row of 5 or more '='s marking the start of the topic
  149.                   text.
  150.                c. The topic text.  This is basically the text to be 
  151.                   displayed in the help file.
  152.                d. A row of 5 or more '-'s marking the end of the topic.
  153.           4. The command, \docend, marking the end of the document.
  154.  
  155.           Document Header
  156.  
  157.           The optional document header may contain commands which will be 
  158.           interpreted globally throughout the document.  Commands 
  159.           changing the font, font size, or first line indent might be 
  160.           appropriate here.
  161.  
  162.           The \docstart command follows the document header to mark the 
  163.           start of the topics.
  164.  
  165.              Example:
  166.  
  167.              \f0 \fs24  (*Times Roman font, 12 pitch for entire file*)
  168.              \docstart
  169.  
  170.           Topic Header
  171.  
  172.           The topic header contains commands defining build tags, context 
  173.           strings, title, keywords, and browse sequence number as 
  174.           appropriate for the topic.  Topic global formatting commands 
  175.           may also be included.  The topic header section is terminated 
  176.           with a row of 5 or more '='s.
  177.  
  178.              Example:
  179.  
  180.              \title Table of Contents`
  181.              \topic contents`
  182.              \keyword contents`
  183.              \f0 \fs24   (* Times Roman font, 12 pitch for this topic *)
  184.              ============  (* end of topic header *)
  185.  
  186.           Topic Text
  187.  
  188.           Text for the topic is entered here.  Rules for text entry are:
  189.  
  190.              Paragraph ends are marked with a grave accent, '`'
  191.  
  192.  
  193.  
  194.                                    3
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.              Blank lines will appear as blank lines.
  207.  
  208.              By default, paragraphs are left justified.  The indenting of 
  209.              the paragraph is set by the indenting of the first line of 
  210.              the paragraph.  Indenting of lines after the first is 
  211.              ignored.
  212.  
  213.              Carriage returns and linefeeds within the paragraph are 
  214.              ignored as far as the final results are concerned.
  215.  
  216.              Commands may be interspersed within the text for special 
  217.              effects.  The commands themselves won't appear in the final 
  218.              result.
  219.  
  220.              Examples:
  221.  
  222.              |   Here is a typical paragraph.  It will appear in the font
  223.              |   and pitch specified in the topic header or document 
  224.              |   header.  It is left justified and indented by 360 twips
  225.              |   because the first line is so indented.  The paragraph
  226.              |   is terminated with a grave accent character.`
  227.  
  228.              |   \b\fi480 Here is another paragraph.  It will appear in
  229.              |   bold font because of the \b command.  It will also be
  230.              |   be indented by 360 twips and left justified.  The 
  231.              |   \fi480 will cause the first line of the paragraph
  232.              |   to be indented an additional 480 twips.`
  233.  
  234.  
  235.  
  236.         COMMAND SYNTAX
  237.  
  238.         Commands for RTFGEN and RTF commands passed thru to the help 
  239.         compiler have a similar syntax.  Commands start with a backslash 
  240.         followed by a LOWERCASE alpha symbol.  Some RTF commands 
  241.         have a numerical value attached.  Some RTFGEN commands have an 
  242.         additional parameter string.
  243.  
  244.           Examples:
  245.  
  246.           \box
  247.           \topic <topic name>
  248.           \fs24          RTF command with number
  249.           \fi-720        '-' sign may be used if appropriate
  250.  
  251.         When commands are mixed with text, a trailing space may be 
  252.         required as a delimiter.  The first space following a command is 
  253.         considered part of the command--additional spaces are part of the 
  254.         text.
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                                    4
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.         RTFGEN COMMANDS
  273.  
  274.         Topic Header Commands
  275.  
  276.           \buildtag <parameter string>`
  277.           \topic <parameter string>`
  278.           \title <parameter string>`
  279.           \keyword <parameter string>`
  280.           \browse <parameter string>`
  281.  
  282.         These commands correspond to the *, #, $, K, and + footnotes 
  283.         described in the help compiler documentation.  Each topic header 
  284.         will contains one or more of these commands as appropriate 
  285.         (ordering is unimportant).
  286.  
  287.         The parameter string should--
  288.  
  289.           have format and contents exactly as described in the help 
  290.           compiler documentation for the equivalent footnote.
  291.  
  292.           be entirely on one line.
  293.  
  294.           be terminated by an end of paragraph mark (grave accent).
  295.  
  296.         More than one \keyword command may be used if the number of 
  297.         keywords would exceed the allowable editor line length.
  298.  
  299.           Examples:
  300.  
  301.           \topic proc_deleting_text`
  302.           \title Deleting Text`
  303.           \browse procedures:020`
  304.           \keyword delete;clipboard`
  305.  
  306.  
  307.         Cross References
  308.  
  309.         Cross references may be included in the topic text using the 
  310.         format:
  311.  
  312.           [<green text>:<context>]
  313.  
  314.         where the brackets indicate a cross reference, <green text> will 
  315.         appear highlighted, and <context> is the topic context string for 
  316.         the jump destination.
  317.  
  318.           Example:
  319.  
  320.           To change the color of an existing object, the object is first
  321.           [selected:selecting].  Its color may then be changed.`
  322.  
  323.  
  324.  
  325.  
  326.                                    5
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.         Definitions
  339.  
  340.         Definitions may also be included in topic text by enclosing them 
  341.         in double brackets:
  342.  
  343.           [[<green text>:<context>]]
  344.  
  345.           Example:
  346.  
  347.           Each space is equivalent to 120 [[twips:twip_def]].`
  348.  
  349.  
  350.         Bitmap Commands
  351.  
  352.           \bml <filename>
  353.           \bmr <filename>
  354.           \bmc <filename>
  355.  
  356.         These commands are used to insert bitmaps within the topic text.  
  357.  
  358.           Example:
  359.  
  360.           A bitmap may be placed in a sentence \bmc arrow.bmp , just like 
  361.           any character.`
  362.  
  363.         It's also possible to use a bitmap to cause a jump or bring up a 
  364.         definition as:
  365.  
  366.           Press here [\bmc button.bmp:jump_dest] for more information.`
  367.  
  368.  
  369.         Block Formatting Commands
  370.  
  371.           \blockstart <commands>`
  372.           \blockend
  373.  
  374.         The blockstart, blockend commands define a block over which a set 
  375.         of RTF commands will apply.  These commands are used mainly when 
  376.         laying out tables where formatting is somewhat complex.  An 
  377.         example of their use is given later in the tabbing commands 
  378.         section.
  379.  
  380.         The block formatting commands may be nested to a level of 4.
  381.  
  382.  
  383.         RTF COMMANDS
  384.  
  385.         RTF commands have no effect on RTFGEN but rather are passed along 
  386.         to the help compiler to achieve certain effects.
  387.  
  388.         In the following, some of the RTF commands which seem appropriate 
  389.         for use in help files are listed.  While there are a good many 
  390.  
  391.  
  392.                                    6
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.         listed, keep in mind that in most help files only a few will be 
  405.         required.
  406.  
  407.         Font Commands
  408.  
  409.         Fonts are refered to by number.  Number vs font is set by the 
  410.         font table in the HEADING file.  For the HEADING file supplied:
  411.  
  412.           0  Times Roman
  413.           1  Symbol
  414.           2  Helv (default)
  415.           3  Courier
  416.  
  417.         You can add fonts or change the order by editing the HEADING 
  418.         file.
  419.  
  420.           \f000            change to font 000
  421.           \fs000           set font size in half points
  422.           \plain           plain text (as opposed to bold, italic)
  423.           \b               bold
  424.           \i               italic
  425.           \ul              underline
  426.           \uldb            double underline
  427.           \uld             dotted underline
  428.           \strike          strikethru text
  429.  
  430.         The scope of font commands may be document global (placed in 
  431.         document header), topic global (placed in topic header), 
  432.         paragraph global (placed at start of paragraph), or character or 
  433.         word global (scope defined with {..}).
  434.  
  435.           Examples:
  436.  
  437.           \b This paragraph will appear in bold text.`
  438.  
  439.           This paragraph is {\ul mostly} in plain text with a {\b bold} 
  440.           and an {\i italicized} word.  {\f0 Fonts and \fs30 pitch} can be 
  441.           temporarily changed.`
  442.  
  443.         Paragraph Commands
  444.  
  445.           \par             end of paragraph.  RTFGEN handles this.
  446.           \pard            reset to paragraph defaults.  RTFGEN handles 
  447.                            this.
  448.           \li000           left paragraph indent in twips.  RTFGEN 
  449.                            handles this.
  450.           \fi000           first line indent.  May be negative.
  451.           \ri000           right paragraph indent.
  452.           \sb000           space below paragraph.
  453.           \sa000           space above paragraph.
  454.  
  455.           \ql              left justified (default)
  456.  
  457.  
  458.                                    7
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.           \qc              paragraph is centered
  471.           \qr              right justified
  472.  
  473.           \box             paragraph is surrounded by a box
  474.           \brdrl           left border
  475.           \brdrb           bottom border
  476.           \brdrr           right border
  477.           \brdrt           top border
  478.           
  479.         The scope of paragraph commands may be document global (placed in 
  480.         the document header), topic global (placed in the topic header), 
  481.         or paragraph global (placed at the start of the paragraph).
  482.  
  483.           Examples:
  484.  
  485.           |\box\qc This paragraph is surrounded by a box and is centered.`
  486.  
  487.           |      \fi-360 The first line of this paragraph overhangs by 
  488.           |      about 3 characters.  Note that RTFGEN has already 
  489.           |      indented the paragraph 720 twips because of its 
  490.           |      interpretation of
  491.           |      the 6 character indentation on the first line.`
  492.  
  493.  
  494.         Tabbing Commands
  495.  
  496.         In RTFGEN, either the tab character or the RTF command, \tab, may 
  497.         be used to produce a tab in the help file.  By default, tabs are 
  498.         every 720 twips (about 6 characters).  If neat columns are 
  499.         desired with proportional fonts, tabs are a must.
  500.  
  501.           \tab             causes tab
  502.           \tx0000          defines tab position in twips.  May be used 
  503.                            multiply and should be used prior to using 
  504.                            tabs.
  505.  
  506.         The following should be used just prior to the \tx000 command to 
  507.         which they are to apply:
  508.  
  509.           \tqr             tab is right justified
  510.           \tqc             tab is centered
  511.  
  512.         The \blockstart..\blockend commands may be used to prepare the 
  513.         format for a table.
  514.  
  515.           Example:
  516.  
  517.           \blockstart \li1000\tqr\tx2700\tqc\tx4000` (* tab setup *)
  518.           \ul Left\tab Right\tab Centered`  (* underlined table heading *)
  519.           Data1\tab 1234\tab 12345`
  520.  
  521.  
  522.  
  523.  
  524.                                    8
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.           ABC \tab 12\tab 3333444`
  537.           XYZdef\tab 45678\tab 9`
  538.           \blockend
  539.  
  540.         REFERENCES
  541.  
  542.         The following files may be found on CompuServe in several 
  543.         locations.  To find them use the IBM file finder (GO IBMFF).
  544.  
  545.           RTF.TXT          Info on the RTF syntax.  Many more commands 
  546.                            are listed than given here.
  547.           QDHELP.LZH       Another system to produce help files using an 
  548.                            ASCII editor.
  549.  
  550.  
  551.         COPYRIGHT
  552.  
  553.                 (C) Copyright 1992 by L. David Baldwin.
  554.                           All Rights Reserved
  555.  
  556.         RTFGEN may be copied and distributed freely providing that no fee 
  557.         is charged and it is not part of a package for which a charge is 
  558.         made.
  559.  
  560.         Please report all bugs, suggestions, and problems to Dave 
  561.         Baldwin, CompuServe ID #76327,53.
  562.  
  563.              22 Fox Den Rd., (Summer)     144 13th St. East,  (Winter)
  564.              Hollis, NH 03049             Tierra Verde, FL 33715
  565.              (603) 465-7857               (813) 867-3030
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.                                    9
  591.  
  592.  
  593.  
  594.  
  595.