 -----------------------------------------------------------------------------
  __    ___  ___
 /  \  |__  |__
 \__/  |    |
 

 An Informal Documentation Formatter

 -----------------------------------------------------------------------------







                                    WRITER'S GUIDE

                               Vassilis V. Dimakopoulos


                         --- Last Revision: January 1993 ---




                                   QUICK OVERVIEW
  
  

          OFF will do certain things for your documents, like

             format your paragraphs
             center lines
             put attributes on the screen (e.g. bold, reverse, etc.)
             create lists of things

          Just write your document in any text editor without worrying for
          the visual beauty of it.  You  only  have  to  put  some  simple
          keywords in some places that OFF will understand later to format
          your document. When finished just run OFF on your file and watch
          the result.

          Consult the OFF Reader's Guide for OFF' s options.




                                      STARTING
  
  

          Your document consists of paragraphs and commands. The  commands
          affect the appearance of paragraphs. A paragraph  is  a  set  of
          contiguous lines that ends with a blank line. This means that  a
          blank line starts a new paragraph. The job of OFF  is  basically
          to format the paragraphs by adding/deleting spaces so  that  all
          lines in a paragraph are both right and  left  indented  by  the
          same amount. An example follows:

     Document                                                        OFF output
  
     As I was walking down                       As I was walking down the road
     the     road   next                         next to my  house  I  heard  a
     to                                          voice:
     my house I heard a voice:
                                                 "You started a  new  paragraph
     "You started a new                          you stupid!"
     paragraph you stupid!"

          All the commands that OFF understands have the '%' character  in
          front of them, e.g. '%center', '%macro'. Then the  command  name
          follows, without any space between the '%' and the command name.
          A space before or after a command is optional.

          If you want to actually print the character '%', precede it with
          a backslash (\). If want to print the backslash, precede it with
          another backslash (or else it will be ignored):

     Document                                                        OFF output
  
     Some characters: \%, \\, \\\%                    Some characters: %, \, \%

          In most of the cases you won't need to use (m)any commands.  For
          example if you are writing a letter to  somebody  then  probably
          you just want OFF to format your paragraphs (instead of doing it
          by hand!) and nothing else.

          In case you want to do fancy things  (e.g.  center  some  lines)
          then you probably need to know some of the commands OFF  offers.
          Tutorial sections for the commands follow and the complete  list
          is given for reference at the end of this document.




                                     ATTRIBUTES
  
  

          OFF has 4 commands  to  control  the  appearance  of  text  when
          displayed or printed:

                            %bold, %norm, %rev, %under.

          %bold makes text appear in bold style; %rev  makes  text  appear
          reversed (black characters on white background or  vice  versa);
          %under produces underlined  text;  %norm  resets  everything  to
          normal.

          NOTE: When OFF output is sent directly to a printer ( -p command
          line  option,)  then  reversed  characters  actually  appear  as
          italics.

     Document                                                        OFF output
  
     Different attributes:                              Different attributes:

     %bold bold %rev reverse %under                     bold reverse underlined
     underlined 




                               LINE CONTROL COMMANDS
  
  

          You can tell OFF to treat a line of text in a special way, using
          the commands:

                           %center, %right, %trio, %verb.

          %center will center a line; %right will flush a line towards the
          right end of the screen; %trio will produce a line consisting of
          3 parts: a flushed-left, a centered and  a  flushed-right  part;
          %verb will produce a line preserving all the  spaces  you  typed
          (i.e. verbatim line, unlike lines inside paragraphs.)

          When OFF meets any of the above commands in your document,  then
          it will read the rest of the line and process it accordingly.

     Document                                                        OFF output
  
     Look at the following three lines,      Look at the following three  lines
     that illustrate \%center,               that illustrate  %center,  %right,
     \%right, \%trio and \%verb.             %trio and %verb.

     %center Centered                                     Centered
     %right  Flushed right                                        Flushed right
     %trio L %center C %right R              L               C                R
     %verb Lots       of  spaces    !        Lots       of  spaces    !

          As you can see in the last example, a %trio line should be typed
          as

            %trio <left text> %center <center text> %right <right text>

          to create the 3-part line. You can omit any of the  3  parts  if
          you wish. For example,
                       %trio <left text> %right <right text>
          will produce a line with a left and a right part only.

          Some things should be noted about the %verb command:
          (a) it outputs spaces exactly as they appear in  your  document,
          even if these spaces are preceded by a command. For example,
                                  %verb a %bold b
          will produce
          --> a  b
          while,
                                   %verb a%boldb
          will produce
          --> ab
          So watch your spaces!
          (b) keep in mind that the 1st  space  appearing  after  a  %verb
          command is always ignored.
          (c) no indentation exists for verbatim lines, i.e. output begins
          at column 0 always.

          Inside a line that is to be formatted by the above commands, OFF
          only understands the  %bold,  %endcol,  %newpage,  %norm,  %rev,
          %startcol, %under, %[ and %] commands. The last two commands  do
          not make any sense inside a %verb line, of course.


          In the case you want to have many lines formatted by  the  above
          commands, instead of typing the command name in the beginning of
          each line, you can use the %begin command, as follows:

          %begin <command_name>
          ...
          ... (lines to be processed)
          ...
          %end

          Do not forget the %end at the end!

     Document                                                        OFF output
  
     Here is a bunch of centered                    Here is a bunch of centered
     lines, using the \%begin center                lines,  using  the   %begin
     command:                                       center command:
     
     %begin center                                           First line
     First line                                           Second line now
     Second line now                                       The last line
     The last line
     %end

          You should keep in mind that whatever follows in the line  of  a
          '%begin <command_name>' or an '%end' is ignored.




                                       LISTS
  
  

          OFF can easily create lists of things, using the %list  command.
          A list consists of items and each item consists  of  paragraphs.
          The items can be either numbered or marked with  a  symbol.  The
          %list command may optionally  be  followed  (immediately)  by  a
          number or a character. The rest of the line where  '%list'  lies
          is ignored.

          Rules:

             If nothing follows  the  %list  command  then  the  list  is
              assumed to be a marked one and the symbol used  for  marking
              each item is the '' character (like this list of rules!).
             If a character follows the %list command then the list  will
              be a marked one but the symbol used for marking is the given
              character.
             If a number follows the %list command then the list will  be
              a numbered list, the first  item  being  numbered  with  the
              given number.

          Each item should start with the %item command. You can omit  the
          %item command from the first item of the list, but if a list  is
          a numbered one then numbers won't  come  out  right:  if  N  was
          normally the first number, the first item will be numbered  with
          N-1. The list should  finish  with  an  %endlist  command.  Some
          examples follow:

     Document                                                        OFF output
  
     %list                                                         First item
     First item                                                    Second item
     %item Second item 
     %endlist                                                   *   First item
                                                                *   Second item
     %list * IGNORED!
     %item First item                                           5.  First item
     %item Second item                                          6.  Second item
     %endlist                                                   7.  Third item

     %list 5 (if there was not an %item below, we would start with 4)
     %item First item
     %item Second item
     %item Third item
     %endlist

          NOTES: OFF does not allow a list within a list. When the list is
          a numbered one then (a) OFF  always  puts  a  period  after  the
          number and (b) reserves 2  positions  for  the  number,  so  the
          maximum number can be 99.




                             PARAGRAPH CONTROL COMMANDS
  
  

          As shown in the introductory notes, when OFF reads  a  paragraph
          it treats newlines (or carriage returns) as spaces and does  not
          start a new line at the output. If you  want  to  force  OFF  to
          start a new line in a certain place in a paragraph use the (very
          useful) %nl command as shown in the following example.

     Document                                                        OFF output
  
     Here is a normal                                Here is a normal paragraph
     paragraph for OFF.                              for OFF.

     Here is a normal %nl                            Here is a normal
     paragraph for OFF. %nl (NOT !)                  paragraph for OFF.
                                                     (NOT !)

          We also mentioned that (except for a %verb command) OFF  ignores
          spaces when formatting. But there are some cases where you  want
          a part of your text that  includes  many  spaces  to  be  output
          exactly as it is written. In this case the %[ <text> %]  command
          is for you (<text> is the text to be output as it is.)

     Document                                                        OFF output
  
     If %[  x = 2  %] is                              If   x = 2   is true then
     true then we should ...                          we should ...

          The %[ ... %] command should not  be  confused  with  the  %verb
          command, since they differ in two major issues:
          1.  %verb creates a line while %[ ... %] creates a word that can
              appear inside a paragraph.
          2.  Commands used inside a %[ ... %] have no  effect  (at  least
              immediately).

          The %[ ... %] command can be used inside centered, flushed-right
          and trio lines as well.


          Now, a different issue. OFF normally indents the first line of a
          paragraph by 4 spaces (because it looks nicer).  But  maybe  you
          want a certain paragraph not to be indented at all. In this case
          you can use the %noindent command:

     Document                                                        OFF output
  
     This is a nice paragraph                          This is a nice paragraph
     but i prefer the next one not                 but i prefer  the  next  one
     to be indented.                               not to be indented.

     %noindent This paragraph looks                This paragraph looks  better
     better (I suppose.)                           (I suppose.)

          You should be careful that the %noindent command should  be  the
          first thing that appears in a new paragraph  or  else  OFF  will
          postpone the 'noindentation' for the next paragraph.

          Now,  is  may  seem  to  you  that  every  paragraph  should  be
          unindented, or that is should be  indented  by  30  spaces.  OFF
          allows you to control the amount of paragraph  indentation  with
          the %parindent command. Use it as follows:

                                  %parindent <num>

          where <num> is the number of spaces you want your  paragraph  to
          be indented. If <num> is zero, then indentation is removed  from
          every paragraph in your document. In the  latter  case  you  may
          (highly unprobable) want to actually have a paragraph  indented.
          You can then use the %indent command (exactly the way  you  used
          %noindent above) to have your paragraph  indented  by  4  spaces
          (cannot alter that).

          Actually, the %indent command may  be  useful  if  you  want  to
          indent the first paragraph of an item in a list (see the  %list,
          %item  commands).  OFF  normally  does  not  indent  the   first
          paragraph of an item (because it looks better), so you  can  use
          %indent to override that.




                               PAGE CONTROL COMMANDS
  
  

          You can control how pages are treated by OFF using the following
          commands:

                       %pageno, %newpage, %startcol, %endcol.

          The 1st output page is page number 1 and this  number  increases
          by 1 with every new displayed page. To change the page number to
          whatever you want, use the %pageno command as follows:

                                   %pageno <num>

          where <num> is the desired number. <num> should be >=  zero  and
          <= 999. Note that the page number does not  appear  anywhere  in
          OFF' s output unless the header and/or the footer of a page  ask
          for it (see the next section). Be careful that a change  in  the
          page number actually affects only  the  footer  of  the  current
          page, not its header. The effect on the header  takes  place  on
          the next page, so be careful where you want your page numbers to
          appear...

          The %newpage command makes OFF fill the  rest  of  a  page  with
          blank lines and start a new page at the output. Be careful  that
          if this command lies inside a paragraph, the page break will NOT
          occur after the word preceding the %newpage  command.  OFF  will
          finish formatting the  previous  line  (which  may  or  may  not
          include the preceding word(s)) and then start a new line  (which
          probably contains some of the preceding words) in the new  page.
          So, usually,  a  %newpage  command  lies  after  the  end  of  a
          paragraph.

          OFF thinks that it can output text in a screen that has a  width
          of  80  characters.  Also,  OFF  believes  that  you  want  your
          formatted document to appear between (and including)  columns  5
          and 75 . Remember that columns are numbered from 0  to  79.  You
          can change these numbers so that your document is more  wide  or
          more narrow, with the  self-explaining  commands  %startcol  and
          %endcol. These  commands  should  be  followed  by  the  desired
          number. A word of advice: experiments  with  very  narrow  pages
          were proven a disaster. A page less  than  about  15  characters
          wide cause OFF to terminate unexpectedly.

          %startcol cannot be less than zero and %endcol  cannot  be  more
          than 79. Also, OFF tries to make sure that %endcol  -  %startcol
          is at least 5 so that it can display at least 5  characters  per
          line.

          Keep also in mind that the page length is assumed to be 24 lines
          whenever the output is  displayed  on  a  screen  and  66  lines
          whenever it is directed to a  printer  or  an  ascii  file.  You
          cannot change these numbers inside your document; the same holds
          for the page width; you can do that only when you run  OFF  with
          the -l and -w options -- see the OFF Reader's Guide




                                 HEADERS & FOOTERS
  
  

          Normally OFF outputs plain pages. In some cases though (like  in
          this document) it is useful to have a line that appears  at  the
          top (a header) and/or a line  that  appears  at  the  bottom  (a
          footer) of every page. OFF has two commands that  allow  you  to
          define a header and a footer: the %header and %footer  commands.
          Actually these commands work  exactly  like  the  %trio  command
          (which see.) Hence, for example, the footer of this document was
          defined as:

             %footer V. Dimakopoulos %right %[O F F %] Writer's Manual

          Whatever commands are allowed inside a %trio  line  are  allowed
          for the header and footer lines too. The only  addition  is  the
          %pn command which  produces  the  current  page  number  in  the
          document. For example, the header of this page was defined as:

                     %header Headers & Footers %right Page %pn

          Note that %pn is allowed only in footers and headers and nowhere
          else. The page number is controlled by the  %pageno  command  as
          explained in a previous section. Two important things should  be
          noted:

          1.  The very first page of the  paragraph  never  has  a  header
              (it's a long story..) If you want it to be  like  the  other
              pages, make  a  'header'  by  yourself  using  the  %center,
              %right, %trio or %verb commands. A footer, though, may exist
              in the first page.

          2.  The header  is  displayed  first,  then  text  is  read  and
              displayed and lastly the footer is displayed. If inside  the
              text you change the page number with a %pageno command, only
              the footer will  be  affected.  Hence  if  the  page  number
              appears in both the header and the footer, there will  be  a
              mismatch. Things of course will settle in the next page.

          The following commands tell OFF whether to actually  output  the
          header/footer or not:

                                    %hshow <num>
                                    %fshow <num>

          If <num> is 0 then starting from the current page, OFF will stop
          outputting the header (if %hshow is 0)  and/or  the  footer  (if
          %fshow is 0). Any positive <num>  will  turn  the  header/footer
          output on. Now, since OFF by default outputs plain  pages  (even
          if there  are  headers/footers  defined,)  after  defining  your
          header/footer you have to explicitly turn output on.

          The final commands that control headers/footers are %hspace  and
          %fspace. Normally, OFF leaves 2 blank lines between  the  header
          and the text of a page. Use  %hspace <num>  to set this distance
          to <num> lines. In the same way, you can use  %fspace <num>   to
          set the distance between the text and the footer to <num> lines.
          The default for OFF is again 2 lines.




                                       MACROS
  
  

          Macros are useful when a series of commands or words need to  be
          used repeatedly throughout the document. This way one  can  save
          precious typing time plus  avoid  mistakes.  Each  macro  has  a
          unique name. You have to define a macro first and then  call  it
          every time you need it.

          To define a macro start  with  a  '%defmacro  <mname>'  command,
          where <mname> is the name this macro will have.  After  entering
          the text, give an '%endmacro' command to finish your definition.
          Now, each time you want to call this macro you have to  issue  a
          '%mname' command, i.e. like there was a command  named  'mname'.
          If a macro is named after one of the standard  commands  of  OFF
          then your macro will never  be  called!  Calling  the  macro  is
          equivalent to re-writing the text inside the definition  of  the
          macro. An example follows.

     Document                                                        OFF output
  
     %defmacro rc                                  We  are  going  to   present
     %bold RECIPEE-CAD %norm                       RECIPEE-CAD now. RECIPEE-CAD
     %endmacro                                     is a  revolutionary  cooking
                                                   aid. Unlike ordinary  recipe
     We are going to present                       books,  RECIPEE-CAD  ...
     %rc now. %rc is a
     revolutionary cooking aid.
     Unlike ordinary recipe books,
     %rc ...

          It should be mentioned that everything that follows a '%defmacro
          <mname>' and an '%endmacro' (in the same line) is ignored.

          OFF allows up to 10 macros inside a document. The name  of  each
          macro should be at most 10 characters long. Finally, each  macro
          definition should not exceed 1000 characters.




                                 OFF COMMANDS LIST
  
  

          INDEX  COMMAND            MEANING
   
          (2)    %begin <command> - apply a command to many lines
          (1)    %bold            - start bold output
          (2)    %center          - center a line
          (7)    %defmacro <name> - define a macro named <name>
          (2)    %end             - end a %begin command
          (5)    %endcol <num>    - set last column of output
          (3)    %endlist         - end a list
          (7)    %endmacro        - end a macro definition
          (6)    %footer          - define the page footer
          (6)    %fshow <num>     - display on/off of the footer
          (6)    %fspace <num>    - set distance of footer from text
          (6)    %header          - define the page header
          (6)    %hshow <num>     - display on/off of the header
          (6)    %hspace <num>    - set distance of header from text
          (4)    %indent          - indent a paragraph not meant to be indented
          (3)    %item            - start an item in a list
          (3)    %list            - start a list
          (7)    %macro <name>    - call the macro named <name>
          (5)    %newpage         - start a new page
          (4)    %nl              - start a new line immediately
          (4)    %noindent        - the opposite of %indent
          (1)    %norm            - start normal output
          (4)    %parindent <num> - set global paragraph indentation width
          (5)    %pageno <num>    - set the page number
          (6)    %pn              - show page number in footer/header
          (1)    %rev             - start reverse output
          (2)    %right           - flush right a line
          (5)    %startcol <num>  - set first column of output
          (2)    %trio            - create a 3-part line
          (1)    %under           - start underlined output
          (2)    %verb            - a verbatim line follows
          (4)    %[<text>%]       - produce a verbatim word

          Indices:

          (1) - Attributes
          (2) - Line Control Commands
          (3) - Lists
          (4) - Paragraph Control Commands
          (5) - Page Control Commands
          (6) - Headers & Footers
          (7) - Macros
