Inside Macintosh: Apple Guide Complete /

Chapter 1 Introduction to Apple Guide 1-1

Figure 1-1 The Apple Guide components 1-4

Figure 1-2Figure 1-2A typical Apple Guide panel 1-6

Figure 1-3Figure 1-3A panel that is part of a sequence 1-6

Figure 1-4The Macintosh Sound control panel circled with a coachmark 1-7

Figure 1-5The typical steps a user takes to view an Apple Guide topic 1-10

Figure 1-6A Help menu displaying Macintosh Guide and other guide files 1-11

Figure 1-7A Full Access window 1-11

Figure 1-8 A Full Access Window with a topic area selected 1-12

Figure 1-9A Full Access Window with a topic area and topic selected 1-13

Figure 1-10The first help panel for the selected topic 1-13

Chapter 2 Authoring Tips and Suggestions 2-1

Figure 2-1A Help menu showing the system software guide files and Balloon Help 2-8

Figure 2-2The access window for About Apple Guide 2-9

Figure 2-3A panel in About Apple Guide 2-10

Figure 2-4The Full Access window for Macintosh Guide 2-11

Figure 2-5The Macintosh Tutorial contents 2-12

Figure 2-6The Macintosh Shortcuts contents 2-13

Figure 2-7A Full Access window with default features 2-17

Figure 2-8A Full Access window with an application logo and title 2-19

Figure 2-9A Full Access window with the Topics features selected 2-20

Figure 2-10A Full Access window with Index features selected 2-21

Figure 2-11A Full Access window when Look For is selected 2-22

Figure 2-12A Full Access window with Look For features and the cursor in the search phrase entry box 2-23

Figure 2-13A Full Access window after a Look For search is completed 2-24

Figure 2-14A Single List Access window 2-26

Figure 2-15A Simple Access window with three-dimensional buttons 2-27

Figure 2-16A Simple Access window that takes the user directly to the help information 2-28

Figure 2-17A Full Access window with howdy text 2-29

Figure 2-18A Single List Access window with howdy text 2-30

Figure 2-19Topic headings on the Full Access window 2-34

Figure 2-20A typical panel in Macintosh Guide 2-35

Figure 2-21A pixel grid depiction of a panel 2-36

Figure 2-22A minimized panel 2-37

Figure 2-23A panel with default features 2-37

Figure 2-24A panel design with text, graphic, and button 2-38

Figure 2-25The default prompt for the first panel in a sequence 2-41

Figure 2-26A decision panel 2-42

Figure 2-27A panel with the Full format 2-44

Figure 2-28A panel with the Tag and Body format 2-45

Figure 2-29A panel containing a graphic centered with relative positioning 2-47

Figure 2-30An introductory panel 2-52

Figure 2-31A decision panel with radio buttons 2-53

Figure 2-32A decision panel with checkboxes 2-53

Figure 2-33An action panel 2-54

Figure 2-34An information panel 2-55

Figure 2-35A tip panel 2-56

Figure 2-36A definition panel 2-57

Figure 2-37Some definitions in the Full Access window 2-58

Figure 2-38A related topics panel 2-59

Figure 2-39A transition panel 2-60

Figure 2-40A closure panel 2-61

Figure 2-41A panel with an active Huh? button and an explanation of the button's associated panel 2-62

Figure 2-42A typical panel associated with a Huh? button 2-62

Figure 2-43An Oops panel 2-64

Figure 2-44A Continue panel 2-65

Figure 2-45A panel with GoStart (using the lightbulb icon) and Huh? buttons in the navigation bar 2-72

Figure 2-46A panel with a button centered using relative positioning 2-73

Figure 2-47A panel containing two buttons with absolute positioning 2-73

Figure 2-48The up and down appearance (in grayscale) of a color Continue button 2-75

Figure 2-49The up and down appearance of a black-and-white Continue button 2-75

Figure 2-50A single word of hot text on a panel 2-78

Figure 2-51A panel associated with a single hot-text word on a panel 2-78

Figure 2-52A panel associated with a Huh? button 2-78

Figure 2-53A menu coach 2-79

Figure 2-54A red circle coachmark 2-81

Figure 2-55A red underline coachmark 2-82

Figure 2-56A green X coachmark 2-82

Figure 2-57A red arrow coachmark 2-83

Figure 2-58The SurfWriter sequence for adding a word to the dictionary 2-86

Figure 2-59A Continue panel for a condition in a SurfWriter sequence 2-87

Figure 2-60An Oops panel for a condition in a SurfWriter sequence 2-88

Figure 2-61A sequence in Macintosh Guide for changing the beep sound 2-90

Figure 2-62Avoiding embedding pictures inside of text 2-94

Table 2-1The default prompt set recommended by Apple 2-41

Table 2-2Override prompts by panel type 2-43

Table 2-3Order in which Apple Guide evaluates context checks 2-89

Table 2-4Common translations of Apple Guide terms 2-93

Chapter 3 Planning Your Help Content 3-1

Figure 3-1A flowchart that breaks topic areas into topics 3-8

Figure 3-2A typical flowchart 3-9

Figure 3-3A flowchart for a SurfWriter sequence on creating a custom dictionary 3-11

Figure 3-4An Apple Guide search in response to a search phrase 3-16

Figure 3-5A typical Look For search 3-18

Table 3-1Some words stemmed by Apple Guide 3-14

Table 3-2Examples of index terms derived from sample topics 3-21

Table 3-3Example of ignore words derived from sample topics 3-23

Table 3-4Examples of synonyms derived from sample topics 3-26

Chapter 4 Introduction to Guide Maker 4-1

Figure 4-1Building, testing, localizing, and converting your online assistance using Guide Maker 4-4

Figure 4-2Accessing Guide Maker's utilities 4-5

Figure 4-3Using Guide Maker's menus 4-7

Chapter 5 Creating Your Guide File 5-1

Figure 5-1Creating a build file 5-5

Figure 5-2Building your guide file using Guide Maker's Build utility 5-6

Figure 5-3A successfully compiled guide file 5-7

Figure 5-4Compile options dialog box showing default settings 5-8

Figure 5-5Guide Maker displaying a compile error message 5-10

Figure 5-6Guide Maker displaying a warning message 5-11

Figure 5-7The Utilities menu 5-12

Figure 5-8The Menu Appearance dialog box 5-13

Figure 5-9A guide file and its guide file addition, or mixin 5-14

Chapter 6 Testing Your Guide File 6-1

Figure 6-1The Diagnose window 6-4

Figure 6-2The "All messages" debugging option 6-7

Figure 6-3The Test Look For window 6-9

Figure 6-4A parsed phrase in the Test Look For window 6-10

Figure 6-5Results of a search 6-12

Figure 6-6A Scopes and Keys report 6-14

Figure 6-7A Names to IDs report 6-15

Figure 6-8An Index Sort Strings report 6-16

Figure 6-9The Options dialog box 6-17

Figure 6-10A Guide file Info report 6-18

Chapter 7 Localizing Your Guide File 7-1

Figure 7-1The Localize window 7-4

Figure 7-2The Localize window with files and folders specified 7-4

Figure 7-3Examples of text resources 7-7

Figure 7-4Text resources for panels, index terms, and Look For content 7-8

Figure 7-5Translating a text string 7-9

Table 7-1The 'TEXT' resource names and the associated text strings 7-10

Chapter 8 Converting Windows Help Files 8-1

Figure 8-1Converting your Windows Help files using Guide Maker's Convert utility 8-5

Figure 8-2A successfully converted Windows Help file 8-6

Figure 8-3A Windows Help file and its converted Guide Script source file 8-7

Figure 8-4Creating an interface for your help content 8-8

Figure 8-5Constructing an interface for a sample source file 8-10

Appendix A Guide Script Command Abbreviations A-1

Table A-1Command abbreviations A-1

Appendix B Guide Script Commands and Parameters Quick Reference B-1

Table B-1Commands quick reference B-1

Appendix C SurfWriter Guide and Its Source Files C-1

Figure C-1The organization of the source files for SurfWriter Guide C-2

Figure C-2The access window with Topics selected C-12

Figure C-3A panel with radio buttons C-18

Figure C-4"How do I add a word to the dictionary?" panels C-25

Figure C-5"How do I create a custom dictionary?" panels (automatic branch) C-29

Figure C-6"How do I create a custom dictionary?" panels (manual branch) C-30

Figure C-7The Index window C-39

Figure C-8Matching a search phrase C-44

Figure C-9Results of an intersection between two index terms C-48

Listing C-1A build file ("Build file SURF.src" file) C-3

Listing C-2Events, navigation buttons, and formats (from the "Setup and Access Window.src" file) C-6

Listing C-3Prompt sets (from the "Setup and Access Window.src" file) C-7

Listing C-4Help menu information (from the "Setup and Access Window.src" file) C-8

Listing C-5Access window startup (from the "Setup and Access Window.src" file) C-9

Listing C-6Finder version information (from the "Setup and Access Window.src" file) C-11

Listing C-7Topic areas and topics ("Topic Areas and Topics.src" file) C-12

Listing C-8Placeholder sequence (from the "Sequence Definitions.src" file) C-15

Listing C-9Sequence for "How do I use the tools in the toolbar?" (from the "Sequence Definitions.src" file) C-16

Listing C-10Sequence for "How do I add a word to the dictionary?" (from the "Sequence Definitions.src" file) C-17

Listing C-11Sequence for "How do I create a custom dictionary?" (from the "Sequence Definitions.src" file) C-19

Listing C-12Sequence definitions for Huh?, Definition, and Related Topics (from the "Sequence Definitions.src" file) C-20

Listing C-13Placeholder panel (from the "Panel Definitions.src" file) C-22

Listing C-14Panels for "How do I use the tools in the toolbar?" (from the "Panel Definitions.src" file) C-22

Listing C-15Panels for "How do I add a word to the dictionary?" (from the "Panel Definitions.src" file) C-26

Listing C-16Panels for "How do I create a custom dictionary?" (from the "Panel Definitions.src" file) C-31

Listing C-17Coachmarks ("CoachMarks SW. src" file) C-37

Listing C-18Index terms ("Index Entries.src" file) C-40

Listing C-19Ignore words ("Ignore List.src" file) C-45

Listing C-20Words on the exception list ("Exception List.src" file) C-46

Listing C-21Words on the synonym list ("Synonym List.src" file) C-48

Appendix D Checklist D-1

Figure D-1Tasks required to create a guide file D-1