Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/579b.lha/CustomHelp/CHmanual/Files.ch

Text File | 1991-11-13 | 26KB | 631 lines

\pm Custom Help \ Files
\p Files \ General Data File Info


    Each Data File is divided into logical sections, CH Pages, that are\
assigned to groups in a hierarchal system. The size of a page is not limited\
by the size of the DW. Pages larger than the DW may be scrolled.

    The Base Page is the root of the system. This page is part of the\
program and need not be declared, but it's child list is built from\
the pages assigned to it's group (the Base Group), in the Base Files.

    A convention I have used is to name all Data Files formatted for use\
by CH with either the "Base.#?" pattern, for a Base\
File, or a ".ch" postscript. All the Data Files should be placed in the\
CH Directory with the\
logical name "CHData:" assigned. File Specifications default to the\
CH Directory, thereby shortening their file name parameters to the\
file name only, rather than the full path name.
\rPage Specifiers

\p The Base Page

\w
    Understanding the following depends on a knowledge of these terms:

        Base Group:        The root Page Group for the system
        Base File:        Any file containing Child Pages of the
                            Base Group, residing in the CH Directory
                            with a file name that starts "Base."
        Base Page:        The Parent Page of the Base Group. The
                            Page Name of this page is "Base"
\W
    The Base Page is the root of the CH page system. Access to any page\
in the system must by via a path starting at\
the Base Page. The name\
of this page is "Base", making the first group name "Base". The Base\
Group consists of the Base Page (the Parent Page for the group), and\
all the pages found in the Base Files, belonging to the Base Group.

    The Base Page is generated automatically by CH when started.\
After determining the location of the CH Directory, CH scans the\
list of file names matching the pattern "Base.#?". These files will\
be made memory resident, while the program is running. Pages specified\
in these files, belonging to the Base Group,  will be used to build\
the Base Page. The files are sorted alphabetically, pages found in file\
"Base.aa" will appear on the Base Page before pages found in file\
"Base.zz".

    The Base Files may be configured differently, depending on your needs\
and the amount of memory you have available. You can have as many, or as\
few, of the help system's pages made permanently resident as you like. The advantage\
of a permanently resident page is that after CH has been started, it can\
be viewed without loading it's file, saving time. The dis-advantage is that it uses\
more memory while the program is running, and more files have to be\
loaded at program startup.

    To make a file permanently resident, do not include the Page Name\
of the Base Group's Child Page in the External Page\
Specification, in the Base File. This forces CH to open it's file, to\
find the Page Name, to build the Base Page's list of children. The file\
will be read in at startup and remain memory resident till CH is\
terminated.

    The External Page Specification for the Base Group Child Page\
may include a Page Name, enabling CH to generate the Base Page without the\
need of opening the file containing the Child Page. If that Child\
Page is accessed, the file containing it will then be opened.

    A minimum Base File contains one External Page Specification for\
a Child Page of the Base Group.

    The Base Files may contain more than one Page, and contain pages\
other than Base Group pages. Everything in the Base Files is made\
resident for the duration of the program.

\p Building a Data File


    The beginning of the Data File may be used for comments. Data in the\
file up to the first Page Specification will not be used by the CH\
program.

    In the following only the first three steps are necessary.

    To prepare a file for CH:
\w

        A. Divide the file into pages.
        B. Create Parent Pages and assign each Child Page
            to a group.
        C. Use External Page Specifications to designate file
            names where external pages are to be found.
        D. Assign Related Items for the pages if desired.
        E. If using Word Wrap insert Word Wrap specifications,
            soft returns and paragraph indentations. (see Word
            Wrap Specifiers for details)
        F. Insert \IItalic\i, \BBold\b, \UUnderline\u, \C6\c4color\o, \XComplement\o,
            etc. special characters.
\rPage Specifiers
\rRelated Item Specifier
\rText Style Characters
\r\Using/Related Items
\rWord Wrap Specifiers
\pm Page Specifiers


    1. Parent (Menu)

    2. External

    3. External Text

    4. Child
\W
\l6    note: case is insignificant for all the special characters used in\
the Page Specifications. The 'P', 'C', 'M', 'T' and 'F' may all be\
either upper or lower case.

\l    All Page Specifications consist of an entire line in the Data File\
starting with a backslash, the character "P", and the type character,\
with no intervening spaces. If the backslash is not\
the very first character on the line it is not a Page Specification.\
The type character defines the page type.

    Every page is assigned to a Parent Page.\
The Group Name is the Page Name of the Parent Page of the group. If\
the page is not the first page in a file, and is a child of the same group as\
the page preceding it, you may omit the group name. The page will be\
assigned to the same group as the prior page in the file.

    In the templates for each Page Spec., anything in square brackets\
is optional. Backslashes not in square brackets are mandatory.

\pc Page Specifiers \ Parent(Menu) Page


    Template :            "\PM [Group Name \] Page Name"
\l3
    A Parent Page is the Menu Page for a group. From this page\
you may go directly to any of the Child Pages in that group by\
simply entering the child number.\
Every Child Page of a group must have a page entry in the same\
file as the Parent Page, following the Parent Page. This entry may be\
either the Child Page itself or an\
External Page Specification if the Child Page is located in\
another file.

    Note, in the template, the backslash between the Group Name and\
the Page Name may be omitted if the Group Name is omitted.

    Parent Pages normally consist of the Page Specification only.\
The menu itself, containing the list of Child\
Pages, is generated automatically by the program.

    Sometimes it is preferable to define a Parent Page explicitly,
typing in your own list of Child Pages.\
This method allows you to set up the columns of Child Pages any\
way you like. You can also combine additional information with\
the page list. The Parent of this page (Page Specifiers), demonstrates\
this.

    If the page consists of more than two lines, it\
will be assumed to be an explicit menu page and the automatic\
Child Page list will not be generated. (see Automatic Menu Page)
\r\Automatic Menu Page

\p External Page


    Template:            "\PF [Group Name] \ [Page Name] \ File Name [\ number]"
\l3
    The External Page creates the link between files for a Group\
with pages in multiple files.

    The Group Name is not necessary if this page specification\
immediately follows a page of the same group.

    If the Page Spec. refers to only one page the Page Name may be\
included. Putting the Page Name here will allow\
the program to know the name of the page in the external file\
without opening the specified file. This can significantly shorten the\
time required for page searching, accessing a Related Item and generating\
Automatic Menu Pages.

    The first two backslashes are always needed, reguardless of whether\
the Group Name and/or Page Name are given.

    The File Name must always be given, it\
is the name of the file where\
the page or series of pages is to be found. If the file is in the\
CH Directory, just the file name is necessary. If it is not in\
this directory the full path name is needed. The file name consists\
of all the characters from the second backslash to either the third\
backslash or the end of the line. Do not use quotation marks even if\
the File Name contains spaces.

    The "\number" is an optional number of pages of the selected Group\
to be found in the specified file. This permits the use of one External\
Page Spec. for multiple pages in a file. If there is only one page, this\
parameter, with it's backslash, is not necessary.

    Note that when using this method, a Page Specification for\
this page or these pages, exists in two files, the one\
containing this External Page Specification, then the file\
containing the actual page. Further extensions are not permitted.\
An External Page Spec. may not point to another External Page Spec.

    If the file named in this Page Spec. does not contain a page of the\
named group, or is a Text File, you will get a "Page Not Found" error.\
If it is not a Data File, the file will be unloaded from memory. Use the\
External Text Page Spec. to reference a Text File.

    The file name portion of the specification may refer to a file directory.\
If it does, the directory will be read and a menu will be generated. See\
Directory Menu Page section for the details.
\r\Directory Menu Page

\p External Text Page


    Template:            "\PT [Group Name \] File Name"
\l3
    An External Text Page is basically the same as an External Page\
except the referenced file will be accessed as a Text File, even\
if it is a Data File. This\
type of Page Spec. must be used if the referenced file is not a\
Data File. It may not be used for a file directory.
\r\\Using/Text Files

    The Page Name and "\\number" options of the External Page Spec. are\
not necessary for an External Text Page Spec. A Text File is treated\
as a single page, so the number of pages is always one,\
and the Page Name is derived from the File Name.

    All files loaded from a Directory Menu Page use this type of Page\
Specification.
\r\Directory Menu Page

\p Child Page


    Template:            "\PC [Group Name \] Page Name"
\l3
    These are pages that do not fall into either of the other three\
catagories. They form the bottom level of the hierarchal system of pages.

\p Files \ Related Item Specifier


    A Related Item Instruction is an quick method of access to a\
logically related page, reguardless of where the related page is in the\
system. Related Items need not be in the same group or same file as the\
original page.
\r\Using/Page Search
\r\Using/Related Items

    To set up a Related Item, in the page data, after the Page Name\
insert a Related Item Specification "\R". This is\
similar to a Page Specification but uses an 'R' in place of the 'P'.\
As in the Page Spec., a Related Item Spec. must use an entire line.\
It must appear as the first two characters on the line with no intervening\
spaces. After the "\R" place a search string for the Related\
Item using the page where the Related Item Specification is found as the\
base of the search. (see Page Search for details of a search string)

    In the Related Item Specification, as in a Page Search, it is not\
necessary to enter an entire Page Name. If you are going down through\
several levels only the last level should have it's entire Page Name\
entered. This name will be used in generating the Related Item list in the\
Related Item Window. The preceeding level Page Names may be truncated\
as described in Using the Program/Page Search.

    Related Item Specifications will not be\
displayed when the page is displayed. Instead these lines go into a\
list that will be displayed if the user initiates the Related Item\
Instruction.

    A page can have any number of Related Items.

\p Automatic Menu Page (AMP)


    Normally a Menu (Parent) Page consists of the Page Specification only.\
When the page is displayed the program\
appends a numbered list of Child Page Names to the Parent Name to make\
the Menu Page. If the page, as it appears in the file, consists of\
three lines or less it will be assumed to be an AMP and will\
have it's child list computed when it is first accessed.

    CH will format the list in one of several ways depending on the size\
of the DW and the number of pages in the list. The list will be double\
spaced if the entire list will fit in the DW in one or two columns.\
Otherwise the list will be single spaced. One column will be used if\
possible, two or three, if not.

    AMPs offer ease of formatting the Data File when you originally\
change a Text File into a Data File and automatic recomputation\
of Child Page Names when altering the number or position of Child Pages\
of a group.

    If the Child Pages of the Menu Page reside in another file or files\
it will be necessary to open those files to find the Page Names if\
they are not found with the External Page Specification. (see\
Page Specifiers)
\rPage Specifiers

    You may create you own list of Child Pages for a Menu Page if you\
wish. This may be useful if the Child Pages are in another file and\
you do not wish to have to open this file to view the list of Child\
Pages. Another reason to input an explicit list is to combine information\
along with the menu list.

\p Directory Menu Page


    If an External Page Spec. points to a file device or directory it\
will be read in and a Menu Page generated. An External Text Page Spec.\
may not be used to point to a file directory. The name of the page\
will be the name of the directory and the Child Page list will contain\
the sub-directories and files within this directory. WorkBench ".info" files\
will not be listed.

    The page list will be sorted alphabetically, with sub-directories\
listed first, then files. All sub-directories will have their names\
followed by the word (Menu). Accessing any sub-directories from here will\
generate another Directory Menu Page. All files accessed in this way\
will be treated as a Text File, rather than a Data File, requardless\
of the presence or absence of Page Specifications.

    The directory will remain\
in memory until it is no longer needed to display the current page or\
a marked page and the unused files are cleared from memory.

    If the referenced directory is on a floppy disk and the disk is replaced\
after the directory is loaded you must ensure the Directory Menu Page\
is cleared from memory before accessing it again. Use the Clear File or\
Clear Unused Files Instruction to remove the page from memory.

    Note that all a directory's files are displayed, even those that can\
not be read as a Text File. Accessing one of these will display garbage.

\p Word Wrap Specifiers


    Word Wrap allows the formatting of paragraphs of text to be adjusted\
for the size of the DW. For the most visually pleasing results some\
things need to be taken into consideration when creating the Data File.

\w----------------------------------------------------------------------------------------------------------
\W
    First, each paragraph must be on a single line. It must have only one\
new line character (ASCII dec. 10), at the end of the paragraph. This\
allows CH to determine\
where to break the paragraph when it is displayed, based on the width of\
the display. There are two ways to do this.

\l3A. You can type the entire paragraph on one line.
\l6    The drawback of this method is that it becomes hard to edit\
a file that has extremely long lines. The line limit of the editor you\
are using may not be enough for the longest paragraph you have.

\l3B. You can use soft returns on all but the last line of the paragraph.
\l6    You create a soft return by placing a backslash '\' at the end of\
the line. CH converts the ending backslash-new line character in the data\
file into a space for display.
\l
\w----------------------------------------------------------------------------------------------------------
\W
\l    Second, some lines or pages depend on data being in a particular column\
to be intelligible. Using special characters in the Data File you may block\
a line or entire page from being wrapped, reguardless of the state of the\
Word Wrap option.

    In order for lines to be wrapped, first the Word Wrap menu option must\
be active (Custom Help/Word Wrap menu checked). If the Word Wrap menu\
option is active lines will actually be wrapped or not depending on the\
Block Word Wrap latch (BWW). To be wrapped both the Word Wrap menu option\
must be active and the BWW latch must be inactive.

    The backslash-w at the beginning of a line, "\\w" will turn the Block\
Word Wrap latch on, inhibiting Word Wrapping. The backslash-W at the\
beginning of a line, "\\W" turns the Block Word Wrap latch back off, allowing\
lines to wrap again.

    Most Menu Pages use columnar data therefore Menu Pages start with\
the BWW latch active. The page data must contain a "\\W" in order for\
Word Wrap to be activated. All pages other than Menu Pages start with\
the BWW latch off.

    The dashed lines on this page are examples of lines that are blocked\
from wrapping. Even though they are longer than the Display Window they\
will not break at the end of the DW.\

\r\Using/Word Wrap
\w----------------------------------------------------------------------------------------------------------
\W
    Third, it is sometimes useful to indent the paragraphs. Use a "\\l##"\
at the beginning of a paragraph to set the indentation of each line\
in the paragraph to ## of leading spaces. The "##" is\
the decimal number of spaces to indent. This indent will remain active\
through the page until another "\\l##" is encountered on the page.

    The maximum indent allows at least 15 characters to be displayed.

\p Text Style Characters


    CH recognized several special character sequences, which are used\
to render page text in Underline, Bold, Italic, Complement or set the\
foreground and background colors.

    The special character sequences all use the backslash as their first\
character. The backslash is followed by the:
\l6
Character        Function
~~~~~~~~~        ~~~~~~~~
    U                Underline on
    u                Underline off
    B                Bold on
    b                Bold off
    I                Italic on
    i                Italic off
    X                Complement on
    x                Complement off
    C#                Background color 0 to 7
    c#                Foreground color 0 to 7
    o                Normal text -- resets all of the above
\l
    The following samples must be displayed with CH, while being viewed as a\
normal CH page. If this file is loaded as a text file, or viewed with an\
editor, the special\
characters will not be converted. Each of the samples first shows what\
the line should look like in the Data File, enclosed in quotation marks,\
then what it looks like when the style sequences are converted.
\w
"This is a test of the \\Uunderline\\u function"
This is a test of the \Uunderline\u function

"This is a test of the \\Iitalic\\i print function"
This is a test of the \Iitalic\i print function

"This is a test of the \\Bbold\\b print function"
This is a test of the \Bbold\b print function

"\\U\\C2This is a test of the underline function with back color 2\\o"
\U\C2This is a test of the underline function with back color 2\o

"\\C3\\IThis is a test of the italic print function with back color 3 \\o"
\C3\IThis is a test of the italic print function with back color 3 \o

"\\B\\C6This is a test of the bold print function with back color 6 \\o"
\B\C6This is a test of the bold print function with back color 6 \o

"\\U\\I\\B\\C3\\c4This is a test of the underlined, italicized, bold print function \\o"
\U\I\B\C3\c4This is a test of the underlined, italicized, bold print function \o

"\\c2This is a test of the \\Upen 2 color\\u \\o"
\c2This is a test of the \Upen 2 color\u \o

"\\c3This is a test of the \\Upen 3 color\\u \\o"
\c3This is a test of the \Upen 3 color\u \o

"\\c4This is a test of the \\Upen 4 color\\u \\o"
\c4This is a test of the \Upen 4 color\u \o

"\\c5This is a test of the \\Upen 5 color\\u \\o"
\c5This is a test of the \Upen 5 color\u \o

"\\c6This is a test of the \\Upen 6 color\\u \\o"
\c6This is a test of the \Upen 6 color\u \o

"\\c7\\C3This is a test of the \\Upen 7 color\\u with background color 3 \\o"
\c7\C3This is a test of the \Upen 7 color\u with background color 3 \o

"\\XThis is a test of the \\UCOMPLEMENT\\u function\\o"
\XThis is a test of the \UCOMPLEMENT\u function\o

\p New File Sample


    In this sample explanation I will make the following assumptions:
\l6A. You have a new file to add to your help system.
B. The name of this file is "PDProgram.doc".
C. This file contains four main sections.
D. Each section will be a CH page.
E. You want a menu for these four pages.
F. This menu will be a child of the Base Group.

\l    To accomplish these objectives the following steps are necessary:
\l6\wA. Create a Base File with an External Page Specification
    for the new Menu Page in the new Data File.
B. In the new Data File create a Parent (Menu) Page for
    the four pages that follow.
C. Insert a Child Page Specifier in the file before each
    of the four sections.
\rAutomatic Menu Page
\rPage Specifiers
\W
\lCreate Base File:
    Using an editor, create a new file named Base.PDProgram. Give it\
a single External Page Specification using the following two lines\
between the quotation marks.

\l6"\PF Base\ PDProgram\ PDProgram.ch"
"PDProgram"

\l    The name of this file must start "Base." or it will not be a Base File.\
This will make the new Menu Page\
that will be created in the Data File a Child of the Base Group.\
The second line in this file allows the Base Page to be built without\
it being necessary to open the new Data File. Save the new Base File in the\
CH Directory.

Create a Parent (Menu) Page:
    Using your editor, open the file "PDProgram.doc".\
At the beginning of the first Child Page insert a Parent Page Specification.

\l6"\PM Base \ PDProgram"

\l    This creates a Menu Page that is a child of the Base Page and\
gives it the name PDProgram. This is the page pointed to by the\
External Page Spec. in the Base File just created.\
"PDProgram" becomes the Group Name for it's Child Pages.

Insert Simple Page Specifications:
    Insert the first Child Page Spec. on the line after the Parent Page\
Spec. This line should be "\PC PDProgram \ Page Name".\
It is the first page of this group, making the Group Name mandatory.
"Page Name" is any name you wish to assign to this page.

    Next you divide the file into logical sections, placing a Child\
Page Spec. at the beginning of each section and assigning a Page Name\
to each. Determine where you want the second page to start, and insert the\
next Page Spec. "\PC \Page Name". This Page Spec. does not require the\
Group Name. It will inherit the group of the previous page.

    Go through the file inserting a "\PC \Page Name" at the beginning of each of\
the two remaining sections. Each page will consist of the data\
from it's Page Spec. to the next Page Spec. or the end of the file.

    If you wish to use Word Wrap with this file go through the file\
inserting the appropiate Word Wrap Specifications. (see Data\
File/Word Wrap Specifiers)
\rWord Wrap Specifiers

    When done inserting Page Specifications save the file in the\
CH Directory, changing the suffix ".doc" to ".ch". The ".ch"\
suffix tells you that the file has been formatted for use by the\
CH program.

    You are now ready to access the file through the menus and display\
the information contained in logical pages divided as you wish.\
If CH is already started open the DW then execute a Restart Instruction\
to reload the Base Files. If CH is not running start it now.

    As an alternative you may make the file accessible to the program\
as a single page by eliminating all the formatting done in the new\
file. Instead do just the External Page Specification in the Base File\
using the file "PDProgram.doc". If the file contains no CH Page\
Specifications the entire file will be read in as a single page. This\
is suitable for small files but large files are more easily read by\
dividing them into pages.

\p CH.cmd File


    The CH.cmd File contains the information CH uses to assign a Command\
to an Instruction. It must reside in the CH Directory.\
Do not edit this file. Commands are configured\
using the Command Edit Instruction. See Using the Program/Commands\
for details.

\r\Using/Commands
\p CH.prefs File


    The CH.prefs File contains your program preferences. It must reside\
in the CH Directory. This is not an\
editable file. Your preferences are set from the Startup Options and any\
settings you change while running CH. When you have the desired configuration\
execute a Save Preferences Instruction to update this file. Whatever you\
have saved will be used the next time the program is run.

    Options specified in CH.prefs will have a lower priority than the\
Startup Options.

    See Starting and Termination/Startup Options for details of the\
startup options.

\r\Start/Startup Options
\p CH.menu File


    The CH menus are optional and definable by the user. The CH.menu file\
must reside in the CH Directory. Edit the CH.menu\
File to select the desired menus, menu items and menu sub items. All\
Instructions are available via the Commands, making the menus\
unnecessary, but to adhere with the normal Amiga user interface you may\
include menus for any or all Instructions. If you do not desire\
the pull-down menus rename or remove the CH.menu file.

    The sample CH.menu File that accompanies CH contains all the\
Instructions. This file may be edited to remove any Instructions\
you do not wish to have a menu item.\
Renaming the file, (e.g. CH.menu.save) will prevent CH\
finding it when the program is started, giving you the basic menu\
only, and saving memory. The basic menu is "Custom Help", with one\
menu item (About), and four sub items (my name and address).

    A list of the Commands and their numbers is available in the Using\
the Program/Intructions by Number Section or by using the HELP key.
\r\Using/Instructions by Number
\w
    The CH.menu File contains three types of entries:
        A. Menu --         "M, Name"
        B. Item --         "I, ##, Name"
        C. Sub Item -- "S, ##, Name"

    Where:
        The first letter must be exactly as shown for each type.
        "##" is the number of each Instruction.
        "Name" is the text to be placed in the menu or item.
\W
    The menus and items will appear in the DW in the same order as they\
are listed in the CH.menu File. The basic menu "Custom Help" can be added\
to by starting the CH.menu File with an item entry rather than a menu\
entry. Each list of items will be attached to the preceding menu. Each\
list of sub items will be attached to the preceding item.