Panorama Help Wizard

The Panorama Help wizard is your guide to Panorama. It contains a vast store of information, along with tools to help you locate and navigate that information. The Help wizard is available with a single click at any time – even if you’re currently using a dialog.

To open the help wizard, choose Panorama X Help from the Help menu. This illustration shows the various components of the wizard.

The basic operation of the help wizard is a simple two step process:

1. Type in a search word or phrase
2. Click on the topic you want to see.

If the topic is a long and complicated one, an optional third step is to click on the subtopic within the page. This jumps directly to that subtopic, potentially saving a lot of scrolling.

The list of subtopics is also convenient for getting a quick overview of the material the current help page covers.

### Using Help Realms (Pre-set Topic Subsets)

The Help wizard contains information about over two thousand topics. That’s a lot of topics, so sometimes you may want to deal with only a subset - for example just tutorials, just formulas, just charts, etc. The wizard provide about three dozen pre-defined subsets that can be selected from a popup menu. These pre-defined subsets are called “realms”. When you first open the Help wizard, the Basics realm is automatically selected for you. The Basics realm contains the most common topics you’ll need to learn about when you start using Panorama.

To pick a different realm, click on the magnifying glass or the name of the realm, then choose from the pop-up menu.

If you want to search from all available topics, choose ALL at the top of the menu.

When you close and then re-open the Help wizard (or even close and re-open Panorama), Panorama remembers what realm is active. If a search doesn’t show the results you expected, you may have forgotten that you have a chosen a realm that is restricting the scope of your search. Choose ALL if you want to make sure that searching covers all help topics.

### Searching for a Topic by Name

To locate a particular topic, click in the search box in the upper left hand corner and start typing. The topic list will show the list of topic names that match. Click the topic you want to see.

### Searching for a Topic by Full Text

When the Full Text Search option is enabled, the wizard will search the entire contents of each help topic, not just the name. For example, if you search for menu item there normally won’t be any results, because there is no topic that contains menu item. But when the Full Text Search option is enabled Panorama will show you that there are dozens of topics that contain that phrase somewhere within the page. (See Searching Within a Page below to learn how to find the exact position of this text within a long topic page.)

You may wonder why the Full Text Search option isn’t enabled all the time. The problem is that this option often will return far too many results. For example, if you do a full text search for menu there will be over 2,000 results! A regular topic name search will return a few dozen results, much more managable.

#### Estimated Page Count of Search Results

When you peform a search (or select a Realm), Panorama will estimate the number of printed pages in the topics that were found. It’s not actually possible to print the pages, but this does give you an idea of how much material was found by the search.

Note: You can print an individual topic by choosing Topic>Open Topic in Browser, then printing it from Safari.

### Using the Breadcrumb Navigation Links

The “breadcrumb” appears at the top of every help page. This includes a link to previously viewed topics (equivalent to the Back button in a web browser), and links to the “parents” of the current page. If you’re viewing a page and you want to back out to a higher level topic (i.e. look at the forest instead of an individual tree), simply click the appropriate breadcrumb link.

### Searching Within a Page

To search within a phrase, type the word or phrase you want to search for in search box in the upper right hand corner of the window. As you type, Panorama will show you the number of matches found within a page.

To jump to the first match, press the Return key or press Command-G. Continue pressing Command-G to find additional matches within the page. Press Shift-Command-G to search backwards within the page. You can also click on the left/right buttons to search backwards and forwards.

### Page Table of Contents

In addition to searching, you can also navigate within a page using the table of contents, which appears in the lower left hand corner of the window. Simply click on any item to jump to it.

You can also access the table of contents by right clicking on the prototype code area, which displays a pop-up menu that includes the table of contents. An advantage of this method is that long section names won’t be truncated.

### Opening Multiple Help Windows

To open a second Panorama Help window, click on the green arrow (or choose New Help Window from the Window menu).

You can open as many help windows as you like, with each window showing a different help topic.

#### Opening a Link in a New Window

To open a link in a new help window, right click on the link and choose Open Link in New Window from the pop-up menu.

You can also open the link in the standard web browser (usually Safari), or copy the link to the clipboard.

### Transferring Help Information to your Project

If you are editing a program or a formula, you may want to transfer information from a help topic into your work. There are several ways to do this. A very simple technique is to simply click on the help contents and select the text you want, then copy or drag the text wherever you want it.

To drag the function or statement name and its parameters, click on the gray arrow in the upper left and drag to wherever you want (you can actually start the drag from anywhere in the box, not just the arrow).

You can also right click on this box for a pop-up menu that includes options for copying the topic (the function/statement and parameters) to the clipboard, or to open this topic in your default web browser (usually Safari).

### Advanced: Using a Formula to Search for Topics

Normally the Help wizard does a simple “contains” text search for the word or phrase you type in. However, the Help wizard is actually a database, so you can also do a precision search using the full power of a Panorama formula.

To give you room to edit a formula, Panorama allows you to expand the search area to fill the entire width of the help window. (You don’t actually have to expand the search area to use a formula, but even the shortest formula won’t fit in the normal sized box, making it difficult to edit.)

For example, suppose you can’t remember how to use the for statement. Searching for the word for produces a lot of matches, because a lot of topics contain the word for. It’s rather tedious to manually search through this long list of topics to find the actual for statement.

What we really want to do is search for the topic that is exactly the word for, with nothing extra. With a formula, this is easy.

#### Help Database Fields

This formula in the previous section works because the topic names are in a field named Page. To write search formulas you’ll need to know what fields are contained in the Help database. Here are all of the searchable fields in this database:

- Page – topic name.
- Filename – name of the actual HTML file containing the topic page.
- Title – topic title.
- PageType – type of page, may be plain, statement, function or operator.
- Tags – comma separated list of tags (used for generating See Also listings).
- Breadcrumb – list of topics that are parents of this topic (separated by > character).
- Description – short description of topic.
- Parameters – names and descriptions of parameters (if any).
- Body – main body of the topic description.
- SeeAlso – comma separated list of tags and topics related to this page.
- History – short summary of changes made to this topic over time.
- PageCount – approximated number of pages for this topic.
- PageTOC – section headers within this page (this is actually a menu formula).
- Created – first version where this topic appeared (for example 10.0.1).
- Modified – most recent version when this topic was changed (for example 10.2).

Note: The Tags, Breadcrumb, Created and Modified fields do not always contain consistent data. (For example you may find a tag that is spelled with both upper and lower case, or singular or plural. We will be working to fix these issues in future versions.)

You can combine multiple fields, operators and functions to build a formula that precisely zeroes in on just the help topics you need. For example, this formula finds the three Panorama operators that take boolean (true/false) parameters.

With a slight modification, this formula can find boolean functions instead:

#### Search Formula Errors

Panorama only does a formula search when you have provided a valid formula. If you type in a formula with a syntax error, Panorama doesn’t realize that this is a formula at all, and it simply does a regular text search (which will probably result in no matches). So keep in mind that Panorama will not display an error message in this situation. This illustration shows a formula with a syntax error, so there are no matches.

If you think there is a syntax error and you want to see what it is, click on the magnifying glass to make the Formula Assistant menu appear, then choose Display Formula Error. An alert will appear with the error message. (Note: The Display Formula Error command only appears if there is an error. If this command is not in the menu, there is no error.)

If the formula has valid syntax but causes an error when evaluated (for example if a field name is misspelled), the error message will be displayed in the topic list.

#### The Formula Assistant Menu

Clicking on the magnifying glass causes the Formula Assistant menu to appear. This menu can help you construct search formulas, and also can help you recall recently used formulas.

The bottom portion of this menu contains nearly two dozen templates for common searches. When you select one of these items, the template will automatically be typed into the search box. (Also, the search box will be expanded if you haven’t already done that.)

Most of the templates contain placeholders for the actual item you want to search for. The placeholder is selected, so all you have to do is type in the actual value to complete the search. In this case this search will find all statements and functions with JSON parameters.

If the search box already contains a formula, selecting another template will append that template to the formula, joined to the original formula with the and operator (you can manually change this to or if needed). In this example, the search has been modified to find only functions that have JSON parameters, excluding statements.

#### The Tags/Breadcrumb Templates

The Formula Assistant menu has two special templates for searching the Tags and Breadcrumb fields. Instead of simply typing in the template and then having you type in the value to search for, these menu items open a dialog that allows you to choose the value you want to search for from a list of values in the database. For example, the Tags dialog looks like this. You can click on any tag to see how many occurences of that tag exist in the help database. Press the Ok button to create a formula to search for that tag (you can also double click on the tag to create the formula).

The dialog has a search box to help you quickly find the tag you want. For example, this illustration shows how to select only tags containing tri, allowing me to quickly locate the trigonometry tag.

The Breadcrumb dialog works exactly the same way, but shows breadcrumb values instead of tags.

#### Accessing Recently Used Formulas

Once you’ve gone to the trouble of creating a search formula, it’s quite likely you’ll want to use it again later. The Formula Assistant menu keeps the dozen most recently used formulas right at your fingertips. To re-search for a formula, simply click on the magnifying glass and select the formula from the top half of the menu. (Note that when you select a recent formula, any formula already in the search box will be erased.)

If you want to manage the list of recent formulas, or access formulas beyond the most recent dozen, choose the Recent Query Formulas command from the menu. This opens a dialog that allows you to see and edit all of the formulas that have been used in the help wizard.

You can use this dialog to delete formulas, copy and paste them to a new location to rearrange the list, or copy a formula and then paste it into the search box.

### Advanced: Submitting Corrections

Let us apologize in advance, you may find errors in Panorama X’s voluminous documentation. In the past, a number of Panorama users have been kind enough to report mistakes to us, so with Panorama X we’ve actually provided a way that you can make the correction yourself and submit it to ProVUE for publication. In most cases, making the correction will actually be simpler than reporting a mistake was in the past!

#### Markdown

The Panorama X documentation is written using a formatting system called Markdown. Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, which is then automatically converted to HTML. Markdown is much simpler than HTML, and has become very popular in recent years (it was originally invented by John Gruber in 2004).

There are many resources for learning Markdown. The basics are very simple, and can be learned in a few moments. Since there is a wealth of online resources for learning Markdown, we won’t attempt to teach it here. However, if you look in the Corrections menu you’ll see links to some of these online resources.

You’ll probably want to preview any changes you make. To do that you’ll need to install Markdown on your system. Panorama X actually uses a slightly enhanced version of Markdown called MultiMarkdown. MultiMarkdown is free and very easy to install. Just choose Download MultiMarkdown from the Corrections menu and follow the instructions on the web page that appears. It shouldn’t take more than a minute or two.

#### The Corrections Window

The Corrections window allows you to edit the raw source of a documentation page:

If you are simply fixing a typo, just find the typo and make the change. If you installed MultiMarkdown, you can switch back and forth between the raw source and the formatted page using the Edit/Preview buttons at the top.

Use the Notes section at the bottom of the window if you want to submit any comments to ProVUE along with your changes. When the changes are complete, press the Send to ProVUE button in the upper right hand corner. This sends the correction directly to ProVUE without any further confirmation. You can then close the Corrections window. (Note: The changes you have made do not modify your copy of Panorama, and will not show up in the regular Help window, even on your computer, until they are approved by ProVUE.

#### Page Sections

If you look closely, you’ll notice that the documentation is divided into sections: PageHeader, Filename, Descriptions, Parameters, Body, etc. Each section is surrounded by a pair of tags.

You should never edit the tags surrounding the sections. In addition, you should never edit the contents of the Page, Filename, or PageType tags.

To help you keep track of what you’ve done, the top of the window shows you which sections you have modified.

If this area is blank, you haven’t made any changes!

##### Cross Reference Links

In Markdown, a link to an HTML page is written like this:

    [Title][http://www.somesite.com/somepage.html]

To link to another page in Panorama X’s Help system, the title should be the name of that page, and the URL should be left blank. For example, this is how to make a link to the arrayfilter( page:

    [arrayfilter(][]

Panorama will automatically expand [] into the correct link for the page.

##### Tags and SeeAlso

The Tags section contains a comma separated list of tags for this page. These tags can be used for searching, and they can also be used in the SeeAlso section. If the SeeAlso section contains @tag, all of the pages with that tag will be listed in the see also section. You can also simply include a comma separated list of pages in this section, or you can combine tags and pages like this:

    @math,or,and

##### Embedding HTML Tags

It’s rarely necessary, but you can embed HTML tags into the middle of the Markdown content. For example, some pages contain HTML tags for creating tables.

History

Version | Status | Notes
10.0 | New | New in this version.