


                                  FORMTEXT
    ________________________________________________________________________



    FormText
    

    Introduction
    
    FormText is a utility to reorganise a plain text file so that it has
    regular page breaks, margins, headers, footers and a contents page.
    Files processed in this way can be used as a manual, suitable for
    printing on almost any printer.

    The reason for writing it was more to make something useful out of a
    Toolbox tutorial than to provide a brilliant utility. Therefore, the
    formatting code was wriiten for simplicity rather than efficiency.
    Although all formatting is done in RAM it uses a rather slow multi-pass
    process.

    This file has been processed by FormText, but without contents because
    they would look silly with a manual this short.

    The author
    
    Tony Houghton
    271 Upper Weston Lane
    Southampton
    SO19 9HY

    riscos@realh.co.uk                       http://www.realh.co.uk

    Suggestions, presents etc welcome.

    Conditions
    
    The conditions by which FormText is used and distributed are best
    described by the term freeware. This means that it may be freely used
    and distributed, but the author retains copyright. The conditions I
    impose are that the application is distributed without any of its files
    altered, and it is not marketed as a commercial product.

    Subscribers to Archive magazine/disc have access to the source code, to
    be used only for tutorial purposes.

    Installation
    
    If you have an OS earlier than RISC OS 3.6 you need the Toolbox modules
    in the supplied copy of !System. Use !SysMerge to install the new modules,
    the merger within RISC OS 3.5 and 3.6's !Boot is bugged.

    Version
    
    This is version 1.10.




                                    Page 1





                                  FORMTEXT
    ________________________________________________________________________




    Basic use
    
    FormText appears on the icon bar when loaded. To format a file, drag it
    to the FormText icon and a large dialogue box will appear. Fill in the
    details you require and click Format.

    While the text is being formatted the Hourglass shows the percentage
    done. This is a very rough guide, based only on how many stages of
    processing the file has gone through so far. The time taken to complete
    each stage can vary widely.

    When formatting is complete, the main dialogue box closes and is
    replaced by a Save as dialogue box for you to save the formatted file.

    How to set up a text file for formatting
    
    FormText splits text up into lines short enough to fit across the
    configured page, so you should only use line-feeds (ie the Return key)
    where you explicitly want them, such as at the end of paragraphs. To
    enter your text you may find it easier to use the SoftWrap mode in Zap,
    or a word processor like Impression that can save plain text without
    line feeds.

    Tabs are allowed, these will be expanded with a field of 8 characters.

    A line beginning with a certain character is taken to be a heading;
    headings can be underlined and shown in an automatically generated
    table of contents. The 'heading flag' character, which is removed from
    the output file, must have an ASCII value greater than 127; you enter
    which character you want to use in FormText's main dialogue box.
    Recommended characters are  for Risc PC and  for Archimedes, because
    these are available on the keyboard but are rarely used. Do not
    underline your headings, FormText can do this for you.

    Settings in the dialogue box
    

    Page dimensions
    
    'Total height' is the total number of lines per page on the printer.
    'Top margin' lines will be left blank at the top of every page, below
    this 'Header lines' are allowed for the header. Then 'Bottom margin'
    lines are left blank above 'Footer lines' allocated to the footer. If a
    header or footer is too long to fit in its space, including a blank
    line, it will be truncated.

    The 'Total width' is self-explanatory; 'Left margin' spaces are
    inserted at the start of every line, and room is left for 'Right
    margin' spaces at the end of each line, but these are not actually
    inserted.




                                    Page 2





                                  FORMTEXT
    ________________________________________________________________________



    For clarity:

            Total height =  Top margin + Header lines +
                            text height (calculated) +
                            Bottom margin + Footer lines

            Total width =   Left margin +
                            text width (calculated) +
                            Right margin

    Header & footer
    
    Text from these fields is entered at the top and bottom of every page
    respectively. Certain pairs of characters have special meanings:

    |M inserts a line feed.
    %p inserts the current page number.

    To insert a % or |, use %% or || respectively.

    Contents
    
    If the 'Generate contents' button is ticked a contents table is
    generated (may be more than one page), consisting of every heading next
    to its page number. The 'Title' is used as the header of contents
    pages, there is no footer. Page numbers are right-aligned, as many of
    'Leadering char' as necessary are inserted between the entry and its
    page number to guide the eye.

    Save settings
    
    This button saves the settings currently entered in the dialogue box to
    be used as the defaults next time you load FormText.





















                                    Page 3
