Legacy Document

Inside Macintosh: Apple Guide Complete / Part 4 - Scripting Guide Files

Chapter 10 - Guide Script Command Reference / Guide Script Command Descriptions

/ Defining Topics for Topic Areas and Index Terms

<Topic>

You can use the <Topic> command to specify a phrase that appears in the right column (the topics column) in the Full Access window when Topics or Index is the active list and the user selects the header's associated topic area or index term. You can also use the <Topic> command for a Single List Access window.

<Topic> topicPhrase, sequenceName

topicPhrase

A text string that specifies a topic to display in the list of topics. The topic phrase must not be greater than 63 characters. The actual number of characters displayed depends on the font and the available width of the topics column.

sequenceName

A text string that specifies a sequence for Apple Guide to display when the user chooses the topic specified by the topicPhrase parameter. The sequence name must not be greater than 255 characters and must be unique within the first 63 characters.

DESCRIPTION

Apple Guide displays, in the list of topics, the phrase defined in the topicPhrase parameter. Apple Guide displays the topic under its associated header, if any. When the user clicks the Topics button, Apple Guide displays the phrases defined by <Topic Area> commands. When the user clicks the Index button, Apple Guide displays in the index terms area the phrases defined by <Index> commands. When the user selects a particular topic area or index term, Apple Guide displays any headers (and topics) associated with the selected topic area or index term. You associate a topic with a topic area or index term by following a <Topic Area> or <Index> command by a <Topic> command; or you can associate a topic with a particular header by following a <Header> command by a <Topic> command.

The text specified in the topicPhrase parameter is typically a specific topic or a question suffix that follows a header. For example, if a <Header> command specifies the text "How do I", a <Topic> command might specify the text "change the font?".

Headers are not required. However, if you do define a header for a topic area or index term, all topics for that topic area or index term must be grouped by headers. Alternatively, a topic area or index term can have all single topics associated with it.

Apple Guide places an animated triangle next to any header. When the user clicks the triangle, Apple Guide animates it and expands or compacts the topics under the header.

SPECIAL CONSIDERATIONS

A <Topic> command must be preceded by a <Topic Area>, <Index>, or <Header> command. If you define a header for a topic area or index term, all topics for that topic area or index term must be grouped by headers.

EXAMPLES

#specify a topic area with headers and topics
<Topic Area> "Settings"
   #specify header and topics for this topic area
   <Header> "How do I"
      #specify topic phrase and sequence name
      <Topic> "change the default page width?", "SeqDefaultWidth"
      #specify topic phrase and sequence name
      <Topic> "change the default font?", \xAC
               "How do I change the default font?"
      #specify topic phrase and sequence name
      <Topic> "change the default tabs?", \xAC
               "How do I change the default tabs?"
   <Header> "Why can't I"
      <Topic> "remove a tab?", "Why can't I remove a tab?"
      <Topic> "use smart tabs?", "Why can't I use smart tabs?"
#specify index term then header and topics
<Index> "Page width"
   #specify header and topics for this index term
   <Header> "How do I"
      <Topic> "change the default page width?", "SeqDefaultWidth"
      <Topic> "give each page a different page width?", "SeqPageWidth"

#specify index term then header and topics
<Index> "Fonts"
   #specify header and topics for this index term
   <Header> "How do I"
      <Topic> "change the default font?", \xAC
               "How do I change the default font?"
      <Topic> "increase the size of a font?", \xAC
               "How do I increase the size of a font?"
#specify a topic area with topics only (no headers)
<Topic Area> "Settings"
   #specify topics for this topic area
   <Topic> "How do I change the default settings?", \xAC
            "How do I change the default settings?"
   <Topic> "How do I apply settings from another document?", \xAC
            "How do I apply settings from another document?"
   <Topic> "How do I save settings for a document?", \xAC
            "How do I save settings for a document?"

SEE ALSO

For information on the <Topic Area>, <Header>, and <Index> commands, see page 10-125, page 10-135, and page 10-128, respectively. For information on specifying topics for index terms and topic areas for Mixin guide files, see the descriptions of the <Insert Index Header>, <Insert Index Topic>, <Insert Topic Area Header>, and <Insert Topic Area Topic> commands on page 10-195, page 10-196, page 10-192, and page 10-193, respectively.