WinHelp Under the Hood

1. WinHelp Under the Hood

2. Introduction • File Types • Footnote Codes • Link Codes and Attributes • Mid-Topic Jumps and Keywords • The CNT File and Contents Tab • The Map File and Context-Sensitivity

3. Introduction • Help authoring tools (“HATs”) let you add the codes without understanding them. • But if you understand the codes, you can: • Correct errors yourself. • Take shortcuts around your HAT. • Think outside the “box” imposed by the HAT. • This makes you: • More efficient and effective. • More marketable.

4. File Types

5. File Types

6. File Types

7. Footnote Codes

8. Purpose of Footnote Codes • Break material into units that the compiler and viewer recognize as topics. • Insert “place markers” for use when adding links and index keywords.

9. Inserting Footnote Codes • Use Word's custom footnote feature. • Place the pointer at the code insertion point. • Select Insert/Footnote. • Select Custom Mark and type the code symbol. • Click OK to insert the code. • Type the code value in the footnote area. • To move or delete a footnote code: • Select the code character on the title line, not in the footnote region.

10. # Code • Topic ID. The only required code. • Always used at the start of a topic. • Can also be used within the body of a topic to create mid-topic jump targets. • Syntax: • Valid characters - any except # = > @ ! % • Max. length - 255 characters. • Example - # Print_Dialog_Box

11. $ Code • Programmatically specified topic title. Displays on Index and Find tabs. • Always used at the start of a topic. • Syntax: • Valid characters - any standard characters. • Max. length - 255 characters including spaces. • Example - $ Print Dialog Box

12. K Code • Keywords used in the Index tab and by the KLink macro. • Typically used at the start of a topic. • Can also be used within the body of a topic to create mid-topic keyword targets. • Syntax: • Valid characters - any standard characters. • Max. length - 255 characters per keyword and 16,383 characters per K code.

13. K Code - cont’d • Separate multiple entries with semicolons. • Example - K Print Dialog Box;Dialog Boxes, Print;

14. A Code • Keywords used by the ALink macro. • Used at the start of a topic. • Syntax: • Same as the K code syntax.

15. + Code • Browse sequence code. • Used at the start of a topic. • Syntax: • Valid characters - any except # = + @ * ! % • Max. length - 50 characters. • May be sectional - + Sec. Name:Sec. Number • Example - + AcctsPbl:100 • May be full-length using autoname • Example - + tutorial

16. ! Code • Topic entry macro(s). • Used at the start of a topic. • Syntax: • Separate multiple macros with a semicolon • Example: • ! InsertMenu(mnu_utilities,&Utilities,3); Append Item(mnu_utilities,itm_calc,&Calculator,ExecFile (calc.exe)); AppendItem(mnu_utilities,itm_paint, &Paint,ExecFile(pbrush.exe))

17. * Code • Build tag. • Used at the start of a topic, before all other codes.

18. > Code • Default window type when topic is opened from Index or Find tab or via KLink or ALink macro. • Used at the start of a topic. • Syntax: • Follow by type name of default window. • Example - > quickref

19. Link Codes and Attributes

20. Go-To (Jump) Links • To create: • Add the target topic's ID after the link object (text or graphic), with no space. • Double underline the link object. • Format the target topic ID as hidden text. • Example -

21. Pop-Up Links • To create: • Add the target topic's ID after the link object (text or graphic), with no space. • Single underline the link object. • Format the target topic ID as hidden text. • Example -

22. Can You Turn Off Link Attributes? • To turn off the green and underlining: • Begin the target ID with a % symbol. • To turn off the green only: • Begin the target ID with a * symbol.

23. Should You? • Reluctantly, since this: • Violates the de facto standard for text links. • May lead users to think there are no links unless you state otherwise.

24. Mid-Topic Jumps and Keywords

25. Mid-Topic Jumps • Let you aim jumps into the body of a target topic. • Retains the target material’s context so you don't have to arbitrarily break long topics. • Once in the target topic, users can scroll as usual. • Mid-topic jumps in WinHelp 4 don’t work if you turn on Auto-Size Height in the target topic window.

26. Mid-Topic Jump Coding • Uses the standard topic ID code (#) • Syntax: • Any format is okay, but one that denotes a sub-link may make it easier to manage • For example, for mid-topic jumps in a scrolling list of glossary entries, try: • # A, # B, # C • or for mid-topic jumps to subsections of a topic, try: • # root, # working, # current

27. Mid-Topic Keywords • Let you aim index entries into the body of a target topic. • Retains the target material’s context so you don't have to arbitrarily break long topics. • Once users are in the target topic, they can scroll as usual. • Uses the standard K code and syntax.

28. HPJ File Sections

29. Creating the HPJ File • The HPJ is an ASCII file. You can create and edit it in: • Word and save it in ASCII format. • An ASCII text editor, like Notepad. • The HCW utility (for WinHelp 4). • A Help Authoring Tool (HAT). • If you create an HPJ file via HCW or a HAT, edit it in HCW or the HAT.

30. HPJ File Sections

31. HPJ File Sections

32. CNT File and the Contents Tab

33. Contents of the CNT File • The CNT is an ASCII file with the same name as the HLP file and a CNT extension. • Headings - Shown by book icons. Can contain sub-headings and topics. • Topics - Shown by page icons. Display a topic or launch a macro. • Commands - Control the Contents tab's appearance, scope, and operation.

34. The Basic CNT File Codes • :Base HLP-filename[>window-name] - the name of the HLP file. • :Title title text - the Contents tab title. • A level number and topic name: • If the name jumps to a help topic, add an = sign and the target topic's ID. • If the name represents an expandable book or sub-book, do not enter the =ID.

35. Sample CNT File Code • This code: :Base hcw.hlp>proc4 :Title Help Author's Guide :Link shed.hlp ; Help for the Hotspot Editor SHED.EXE) :Link win32.hlp ; SDK Help file (for WinHelp API) 1 Getting Started 2 What is Help Workshop?=BAS_THE_HELP_COMPILER 2 Help Workshop components=SDK_FILES_DOCS 2 Notational Conventions=SDK_NOTE_CONVENTION 1 What's New in Version 4.0 2 WinHelp 4.0 3 Redesigned User Interface 4 New Help Topics dialog box=NEW_WINHELP_INTERFACE 4 New context menu=NEW_WINHELP_CONTEXT_MENUS . . .

36. Sample CNT File Output • Produces this:

37. Map Files and Context-Sensitivity

38. Overview of the Map File • Contains the context-sensitivity codes for help for a Windows application. • Crucial if you are creating Help. • Immaterial if you are creating an online book. • Codes in a map file associate a help topic ID (#) with the map number of an application object.

39. Map File Definitions • The basic code is: #define topic_ID map_number where • #define - C code • topic_ID - ID (# value) of a Help topic • map_number - ID of the associated object • Map_number can be in decimal or C hex. • An object is a field, dialog box, or any other object that will have context-sensitive help. • Example (decimal map number) • #define Specific_Gravity 131271

40. Map File FAQs • Who creates the map file? • You (or your HAT) create the Topic ID column based on your topic titles. • You (or your HAT) create the map number column.

41. Types of Context-Sensitive Help • Screen level. • Simple to develop. • Explains fields and other controls in context. • Violates the de facto Win 95 standard. • Field/object level - What’s This? • Field explanations are highly focused. • Flexible - launchable via right-click or • Requires more resources than screen level. • More complex programming than screen level.

42. Thank you Hyper/Word Services 978-657-5464 nperlin@concentric.net www.hyperword.com