From 262360d4e6fe6e5d027fbc860b1e90aad62f965b Mon Sep 17 00:00:00 2001 From: Graeme Geldenhuys Date: Wed, 25 Aug 2010 16:46:23 +0200 Subject: docview application help completed! --- docview/docs/docview.ipf | 177 +++++++++++++++++++++++++++++++---------------- 1 file changed, 116 insertions(+), 61 deletions(-) (limited to 'docview/docs') diff --git a/docview/docs/docview.ipf b/docview/docs/docview.ipf index 29cb2bb4..2c876ecb 100644 --- a/docview/docs/docview.ipf +++ b/docview/docs/docview.ipf @@ -872,72 +872,127 @@ refid='InternetLinks'.Internet Links :elink.topic. .* Writing Help Files .* ************************************************************ :h2 res=12 id='WritingHelpFiles'.Writing Help Files -:hp2.Writing OS&slash.2 Help Files:ehp2. -:p.OS&slash.2 Help Files are produced using the IPF Compiler&per. IPF stands for -Information Presentation Facility&per. -:p.The IPF Compiler takes a text file written in a language that tells it about -things like headings&comma. links&comma. text and images&comma. and produces -either a &per.INF or &per.HLP file&per. -:p.The official way to obtain the IPF compiler &lpar.ipfc&per.exe&rpar. is from -the OS&slash.2 Developers Toolkit&per. This is included free with eComStation -&lpar.http&colon.&slash.&slash.www&per.ecomstation&per.com&rpar.&per. -:p.Since the language for IPFC is tedious &lpar.for example all punctuation must -be typed as special keywords&comma. like &.comma&per.&rpar. many people use -other tools besides the IPF compiler itself&per. -:p.I use Vyperhelp -&lpar.http&colon.&slash.&slash.www&per.vyperhelp&per.com&rpar. since it is -simple and graphical&per. It can also export to Windows Help&comma. HTML and -others&comma. though it only runs on OS&slash.2&per. Not free&per. -:p.Some other popular options are&colon. -:p.o HyperText&slash.2 IPF Preprocessor -&lpar.http&colon.&slash.&slash.www&per.clanganke&per.de&slash.os2&slash.sw&slash.htext&slash. -.br -&rpar. &endash. preprocesses a simpler starting language into the very difficult -IPF format&per. Free&per. -:p.o HyperMake -&lpar.http&colon.&slash.&slash.www&per.hypermake&per.com&rpar.&per. -Similar&comma. but can also produce Windows Help and HTML&per. -:p.o Sibyl &lpar.which DocView was created with&rpar. comes with an IPF -preprocessor&per. -:p.o IPFEditor from PCS -&lpar.http&colon.&slash.&slash.www&per.pcs&endash.soft&per.com&slash.productipfe212&per.htm -.br -&rpar.&per. Probably the most complete&comma. but significant cost&per. -Note&colon. DocView doesn&apos.t support everything IPFE can do&xclm. -.br -In the past there were many other options&per. Those listed should still be -available and have some support&per. +:hp2.Writing fpGUI Toolkit and OS/2 Help Files:ehp2. +:p. +fpGUI Toolkit Help Files are produced using the IPF Compiler. IPF stands for +Information Presentation Facility and was original designed by IBM. +:p. +The IPF Compiler takes a text file written in a markup language that tells +it about things like headings, links, text and images, and produces +either a .INF or .HLP file. +:p. +The official way to obtain the IPF compiler (ipfc.exe). is from +the OS/2 Developers Toolkit. This is included free with eComStation +(http://www.ecomstation.com). fpGUI doesn't support the OS/2 platform, so we +can't really use the origin IPF Compiler. Luckily for us, open source software +comes to the rescue! A developer from the OpenWatcom (http://www.openwatcom.org) project +implemented a clean room implementation of the IPF Compiler, by simply using the +origin IPF Compiler documentation as a guide. This new compiler is called WIPC, and +is 100% compatible with the original IBM version. +:p. +For your convenience I included the OpenWatcom IPF Compiler as part of fpGUI Toolkit. +You can find pre-built Windows and Linux binaries in the /tools/wipfc/ directory. +:p. +One huge benefit of the WIPFC compiler over the original IBM version, is that it +is much easier to author help files. With the original IBM version the source help text +was very tedious to write. Every symbol or punctuation like a comma, semi-colon, hyphen etc. and to be +written as special "escaped" keyword. This requirement (and labour intensive work) was +luckily removed from the WIPFC version. +:p. +fpGUI also includes the IPF Language Reference document (IPFREF_v4.INF) as part +of fpGUI Toolkit. You can find this INF document in the +/docview/docs/ directory. The IPF language is not hard to learn. There are +45 tags in total, but you don't need all of them to start authoring your own help +files. All markup tags (with the exception of 5 tags) start with a colon and end +with a fullstop. The tags are mnemonic, making it easy to assocciate them with +their function. +:p. +There are still some GUI IPF editors out there, but most of them are only for +OS/2 (and maybe for Windows). The IPF Language is actually really easy to learn +and understand, so you don't really need a special editor. I used my programming IDE +as my editor, and simply supplied it with a syntax highlighter for the IPF language. +No extra tools needed. Just so you know, that is what I used to author this help +document. :-) +:p. +Here is an example of a small IPF document to get you started. I'll also show you +how to compile it into a binary INF file - viewable with DocView of course. ;-) +:p. +Lets create a text file and call it "sample.ipf". Then type in the following using +your favourite text editor. +:xmp. + &colon.userdoc. + &colon.title. Sample INF file... + &colon.h1.Header One + &colon.p.This is a sample file with one header in the table of content. + &colon.p.This is paragraph two of this single header. + &colon.euserdoc. +:exmp. +:p. +Save the document and close your editor. Now we have the source of our first help +file. Now all that remains is to compile it into a binary INF file. +:p. +To use the WIPC compiler, we need to setup an environment variable so the compiler +can find some of it's support files. +:p. +We do this as follows under Linux. +:xmp. + export WIPFC=~/apps/wipfc/ +:exmp. + ...or as follows under Windows. +:xmp. + set WIPFC=C:\apps\wipfc\ +:exmp. + +I normally setup my computer so that those settings are permantantly set when my +computer boots up. I also make sure the "wipfc" executable is setup in the system +search path so I can run it form anywhere on my system. Now we are ready to compile +our help file! + +:xmp. + wipfc -i sample.ipf +:exmp. + +If you typed the document correctly, you should now have +a :hp2.sample.inf:ehp2. file in the current directory. Now you simply +run DocView and open your first INF help file. Well done! + .* ************************************************************ .* Topic Resource IDs .* ************************************************************ -:h2 res=16 id='TopicResourceIDs'. -Topic Resource IDs -:p.:hp2.Topic Resource IDs:ehp2. -:p.Resource IDs are used by authors of online help for applications&comma. to -identify help topics&per. Applications call the Help Manager specifying a -resource ID&comma. either directly using the HM&us.DISPLAY&us.HELP -message&comma. or indirectly via help tables added to their resources&comma. -which PM automatically handles&per. The resource ID is stored in a table inside -the help file&per. -:p.For document authors&comma. DocView offers the ability to see and find -resource IDs&per. -:p.:hp2.Finding by Resource ID:ehp2. -:p.Use Tools &endash. Find Resource ID to search for a specified resource ID in -all opened files&per. -:p.:hp2.Displaying Resource IDs:ehp2. -:p.Use topic properties &lpar.right mouse click &endash. Properties&rpar. to see -which resource IDs are associated with a topic&per. +:h2 res=16 id='TopicResourceIDs'.Topic Resource IDs +:hp2.Topic Resource IDs:ehp2. +:p. +Resource IDs are used by authors of online help for applications, to +identify help topics. When you create fpGUI base applications, the fpGUI +framework will call DocView with the resource ID as parameter, to display the +correct topic for that part of your application. The resource ID is stored in +a table inside the help file. For a developer to use these, they needs to set +the component's HelpType to htContext. +:p. +For document authors, DocView offers the ability to see and find +resource IDs. +:p. +:hp2.Finding by Resource ID:ehp2. +:p. +Use "Tools - Find topic by resource ID" to search for a specified resource ID in +all opened files. +:p. +:hp2.Displaying Resource IDs:ehp2. +:p. +Use topic properties (right mouse click in the Contents tree view - "Topic Properties") +to see which resource IDs are associated with a topic. + .* ************************************************************ .* TopicNames .* ************************************************************ -:h2 res=19 id='TopicNames'. -Topic Names -:p.:hp2.Topic Names:ehp2. +:h2 res=19 id='TopicNames'.Topic Names +:hp2.Topic Names:ehp2. +:p. +Like resource IDs, topic names can be used by developers to link to +help topics from within their application. The developers needs to set the component's +HelpType to htKeyword. :p. -:p.Like resource IDs&comma. topic names can be used by developers to link to -help topics from within their application&comma. using the HM&us.DISPLAY&us.HELP -message with parameter 2 being HM&us.PANELNAME&per. -:p.These are not so often used&per. -:p.DocView can find a particular topic name&comma. using Tools &endash. Find -Topic Name&per. +DocView can find a particular topic name, using "Tools - Find +topic by resource name". + :euserdoc. -- cgit v1.2.3-70-g09d2