Windows 95 Secrets (4th Edition)/Windows95Secrets4thEdition.iso/tools/helpfile/helpgen/demo.mac

Text File | 1995-02-15 | 10.9 KB | 298 lines

.rem(=============================================================)
.rem(DEMO.MAC)
.rem( )
.rem(Created by the HelpGen Help Generator, version 1.21)
.rem(Copyright ⌐ 1994 by Rimrock Software)
.rem(All rights reserved.)
.rem(=============================================================)

.start(main,Contents,DEMO.BMP,Demo Help Contents)
.top(Help)
.top(Table of Contents)
.n
The DEMO help file example makes use of many of the HelpGen
.p(macro,macros) and .p(rtfcmds,RTF commands) that are documented with HelpGen..n
.in
##.j(planhlp,Planning Your Help File)
##.j(createmac,Creating the Macro File)
##.j(usemacros,Using HelpGen Macros and RTF Commands)
##.j(createhpj,Creating the Project File)
##.j(creatertf,Generating the RTF File)
##.j(createhlp,Generating the Help File)
##.j(testhlp,Testing the Help File).n.n
.bj(glossary,DEMO.BMP)   .b(Glossary).n
.un
.n
If you are unfamiliar with how Windows Help works, choose
 .b(Help | How To Use Help) from the Help menu now.
.end

.ent(icon,Information,Demo )
This icon topic .b(MUST) be present.  It is activated by clicking
on the icon in the Table of Contents.  You may place your own
text here..n
\qc
.box
\brdrth
HelpGen and this demo are \'a9 1994 Rimrock Software.  All rights
reserved.
.bend
\ql
.end

.ent(planhlp,Planning Your Help File, )
Planning the layout and contents of the help file is probably
the most important part of creating on-line help.  A poorly
conceived and implemented help file is almost worthless to a user.
They may not be able to find anything they are looking for in the
help file, and if they do find the correct item, it may not help
with their problems..n.n
This part of help file generation doesn't have much to do with the
actual mechanics of creating the help file, but it .b(is) important,
nevertheless.  Some basic steps in planning a help file are detailed
below..n
.in
#b(Outline the Help Subjects)  Plan to have a few major sections, and
many minor sections.  For instance, one way to organize is
to use the basic outline of your user manual.  Another way is shown below:.n.n
\tab\tab .b(Introduction).n
\tab\tab .b(How To).n
\tab\tab .b(Menu Items).n
\tab\tab\tab File.n
\tab\tab\tab\tab Open.n
\tab\tab\tab\tab Close.n
\tab\tab\tab\tab Exit.n
\tab\tab\tab Edit.n
\tab\tab\tab\tab Cut.n
\tab\tab\tab\tab Copy.n
\tab\tab\tab\tab Paste.n.n
\tab This outline can go down as many levels as you want, but anything
more than about 4 levels is too complicated for a normal user to
navigate.  Once you have this basic outline, you essentially have
each of the topics that will be discussed in the help file.  Each
level of the outline except the lowest level corresponds to a single
display page in the help file.  Each topic on the lowest level of the
outline corresponds to a single display page in the help file..n.n
\tab Continuing with our example above, then, the Table of Contents
page would contain the Introduction, How To and Menu Items topics.
If a user clicked on Menu Items, they would move to a page titled
Menu Items, which contains File and Edit topics.  Clicking on the
File item, they would move to a page containing the Open, Close and
Exit topics.  And finally, clicking on Open would move to a page that
explains the File | Open menu item..n
#b(Create Topic Tags)  Each item on each level of the outline should
have a single word 'tag' that can be used to reference it to.  Go
through the outline and create a tag for each outline item.  We will
use these when we add the topics to the macro file..n.n
\tab\tab .b(Introduction) - intro.n
\tab\tab .b(How To) - howto.n
\tab\tab .b(Menu Items) - menuitems.n
\tab\tab\tab File - file.n
\tab\tab\tab\tab Open - fileopen.n
\tab\tab\tab\tab Close - fileclose.n
\tab\tab\tab\tab Exit - fileexit.n
\tab\tab\tab Edit - edit.n
\tab\tab\tab\tab Cut - editcut.n
\tab\tab\tab\tab Copy - editcopy.n
\tab\tab\tab\tab Paste - editpaste.n
#b(Flesh Out the Outline)  What you are really doing is writing a user
manual that will be read on-line in a non-linear (hypertext) fashion.
Much of what you would normally say in a manual will be included in
the on-line help..n.n
\tab Write explanations for each of the items on the lowest level of
your outline.  Use graphics (\'2eBMP files) and/or examples liberally
to explain the subject (a picture really .i(is) worth 1000 words)..n
#b(Mark Definitions)  When you have completely written all the text
for your help file, go back and circle the terms that you think
the user will have trouble with, and that need to be defined.  These
terms will form the basis of your glossary.  The first time such a
term is encountered in .i(any) topic, it should be marked with a
\'2ep or \'2ep1 and should be explained in a \'2epent entry.  Create
a topic tag for each of the terms..n
#b(Create the Macro File)  You are now ready to create and edit a
macro file for your on-line help..n
.un
.end

.ent(createmac,Creating the Macro File, )
Now that you have your help topics outlined and fleshed out, you can
create and edit a macro file for your help..n
.in
#n(1)Continuing with the example we started in .b(Planning Your Help File,)
let's create an initial macro file.  Click on .b(File | Open Macro File)
and type in 'MYHELP' for a file name.  HelpGen will ask if you wish
to create this file.  Click on the 'Yes' button and MYHELP will be
created..n
#n(2)Now let's do some editing on this file.  Click on .b(Edit | Macro File.)
The text editor should appear, with the newly created MYHELP.MAC
displayed in it.  Let's use the DEMO\'2eBMP file for the icon,
change the table of contents header from xxxx to Table of Contents
and add the first level of our outline to the table of contents
topic:.n.n
.[
\'2erem(=============================================================).n
\'2erem(MYHELP.MAC).n
\'2erem( ).n
\'2erem(Created by the HelpGen Help Generator, version 1.21).n
\'2erem(Copyright \'a9 1994 by Rimrock Software).n
\'2erem(All rights reserved.).n
\'2erem(=============================================================).n
.n
\'2estart(main,Contents,DEMO\'2eBMP,Table of Contents).n
\'2etop(Help).n
\'2etop(Table of Contents).n
.n
\'2es.n
\'2ein.n
\'23\'23\'2ej(intro,Introduction).n
\'23\'23\'2ej(howto,How To).n
\'23\'23\'2ej(menuitems,Menu Items).n
\'2eun.n
\'2eend.n
.n
\'2eent(icon,Information,Icon ).n
This icon topic \'2eb(MUST) be present.  It is activated by clicking
on the icon in the Table of Contents.  You may place your own
text here..n
\'2eend.n
.n
\'2eend_file.n.n
.]
Note that we dress up the topics by indenting them (\'2ein and \'2eun)
and by putting a bullet in front of them (\'23\'23).  We shouldn't
compile this until we add the entries for the three jumps we just added:.n.n
.[
\'2estart(main,Contents,DEMO\'2eBMP,Table of Contents).n
\'2etop(Help).n
\'2etop(Table of Contents).n
.n
\'2es.n
\'2ein.n
\'23\'23\'2ej(intro,Introduction).n
\'23\'23\'2ej(howto,How To).n
\'23\'23\'2ej(menuitems,Menu Items).n
\'2eun.n
\'2eend.n
.n
\'2eent(icon,Information,Icon ).n
This icon topic \'2eb(MUST) be present.  It is activated by clicking
on the icon in the Table of Contents.  You may place your own
text here..n
\'2eend.n.n
\'2eent(intro,Introduction, ).n
\'2eend.n.n
\'2eent(howto,How To, ).n
\'2eend.n.n
\'2eent(menuitems,Menu Items, ).n
\'2eend.n
.n
\'2eend_file.n.n
.]
Now we can compile it if we want to, but let's continue.  Next, we
add the second level of the outline.  In this case, it means adding
to the Menu Items topic, and adding new topics for the third
outline level:.n.n
.[
\'2eent(menuitems,Menu Items, ).n
\'2ein.n
\'23\'23\'2ej(file,File).n
\'23\'23\'2ej(edit,Edit).n
\'2eun.n
\'2eend.n.n
\'2eent(file,File Menu,The ).n
\'2eend.n.n
\'2eent(edit,Edit Menu,The ).n
\'2eend.n
.n
\'2eend_file.n.n
.]
We continue to add new jumps and new topics until we reach the last
level of the outline, where all the text will be entered.
.end

.ent(usemacros,Using HelpGen Macros and RTF Commands, )
If you have looked at .b(Creating the Macro File,) you will see that
we have already used many of the basic HelpGen macros.  The
remaining macros and RTF commands are used to primarily dress up
the help file, to make it more interesting and easier to use
for the user..n.n
\li1050\ri1050 For instance, we just used the \\li and \\ri RTF
commands to squish this paragraph down.  This makes it stand out from
surrounding text..n
\li180\ri180
.box
\brdrsh
.b(NOTE:)  Another way to make text stand out is to place it in a box (\'2ebox
and \'2ebend macros).  This is the .i(most) common method used in user
manuals to highlight important information.  This particular box is a
single line box with shading enabled.
.bend
.end

.ent(createhpj,Creating the Project File, )
When we are ready to compile our help file, we will need a project
file to tell the compiler how to compile it.  Follow these steps
when creating a project file:.n
.in
#n(1)Select the .b(Options | Project File) menu item.  Make sure
that all the listed options are set the way you want them.  Keep
in mind that in the shareware version of HelpGen, you can't change
the copyright notice..n
#n(2)Select the .b(Build | Project File) menu item.  Answer 'Yes'
to the question and a project file will be built for you..n
.un
.end

.ent(creatertf,Generating the RTF File, )
When you have finished editing the macro file, you will want to
create an RTF file from the macro file.  Select the
.b(Build | RTF File) menu item to perform this step.
.end

.ent(createhlp,Generating the Help File, )
When the RTF file has been built, HelpGen will enable the
generation of a help file.  Select the .b(Build | HLP File) menu
item and HelpGen will invoke the help compiler that you have
told it to use (see .b(Options | Directories)).
.end

.ent(testhlp,Testing the Help File, )
After the help compiler generates a help file for you (assuming
that it did so with no errors), you can test the file.  To do this,
select the .b(Test) menu item.  HelpGen will invoke the WinHelp
help engine, using your help file.  You can then proceed with the testing..n
.end

.ent(glossary,Glossary, )
.in
.p(macro,Macro).n
.p(project,Project).n
.p1(RTF).n
.p(rtfcmds,RTF Commands).n
.un
.end

.pent(macro,macro, )
The replacement of a long series of .p1(RTF) commands with a single
command word and (optional) series of arguments.
.end

.pent(project,project, )
A file with the extension .HPJ, that contains options that
specifies how a help file is to be built.  Required by the
help compiler.
.end

.pent(RTF,RTF, )
Rich Text Format, a standard text file formatting standard. An
RTF file consists of .p(rtfcmds,RTF commands) and normal text.
.end

.pent(rtfcmds,RTF commands, )
Special commands in an .p1(RTF) file that describe how text is to be
displayed.  These commands start with a backslash (\\) character.
.end

.end_file