Advanced: <<*Ask. . .*>> Commands
Sometimes you want to <<*Ask*>> a question of the end user: Something like "Are there children?" or otherwise "Has a certain condition been met?" Based on the answer provided, you want the program to (1) select text to be inserted or (2) set, or ask to be set, another value.
The <<*Ask. . .*>> commands ask those questions.
<<*Ask. . .*>> commands are siblings to <<*Options*>> and <<*Optional*>> text blocks within a document. The difference between the two is that the <<*Options*>> and <<*Optional*>> text blocks contain substantive text. <<*Ask*>> blocks do not. An <<*Ask . . .*>> command exists simply to ask a question and record the answer for later use. Once answered and recorded, the <<*Ask . . .*>> command is deleted.
The 'secret' to how and why they work is that the answer to each <<*Ask . . .*>> is assigned to a !groupname!. It is the !groupname! that ties values together.
Types of <<*Ask. . .*>> Commands:
Four <<*Ask. . .*>> Commands are available in Pathagoras. Collectively they cover the range of possible 'Asks' that an author would need to implement a full Interview (Read more about the structure of Ask commands in the below article called <<*Ask*>> Elements):
<<*AskOptions*!Children!No children/One child/2+children*>>
<<*AskOptional*!Minors!Are any children <18 years of age?*>>
<<*AskRepeat*!NumChildren!How many children?*>>
<<*AskValue*!Score!What score did student receive on test?*>>
There are three other important commands that bring <<*Ask. . .*>> commands to their full potential. They are briefly described below, with links provided to fuller explanations and examples:
1. The <<*If*>> command. This is a powerful tool that can be used to set a value to a !groupname! based on an answer given in response to an <<*Ask. . .*>> command, or to pose another <<*Ask. . .*>>. Here is an example:
<<*If*!Children!="Yes",<<*AskOptional*!Minors!Are there minor children*>>,!minors!="False">>
2. The <<*Set*>> command. The Set command can be used to hard code a value in the Ask table (or any other) area of the document..
Read more about the <*Set*. . .>> command at this page.
Here are a few additional things you should know about <<*Ask. . .*>> commands
•They are totally optional. If the first appearance of an <<*Options/Optional*>> block in the document provides a prompt that is clear enough for the typical user to make the proper selection, you may choose to not use an <<*Ask*>> command.
•If used, <<*Ask. . .*>> commands are typically placed at the top of the document. That way, all Asks can be posed at the start of the assembly process. (It is also easier to edit questions you will be asking your end users when they are grouped together.)
•<<*Ask. . .*>> commands are all 'plain text''. As such, you can easily copy a good set of <<*Ask*>> commands from one document to another. Doing so will help you to make the questions uniform from document to document.
•If you use <<*Ask. . .*>> commands, you can get rid of the prompts that you may have typed within your <<*Options/Optional*>> blocks. This may result in a significant savings of document 'real estate'.
Placement of <<*Ask* . . .>>, <<*If* . . .>> and <<*Set* . . .>> commands.
<<*Ask* . . .>>, <<*If* . . .>> and <<*Set* . . .>> commands are typically located at the top of the document. That way, it is the first thing that the end-user will encounter during a document assembly session.
However, these commands are typically created last in the source document creation process. The reason is this: unless you know what the <<*Options . . . Optional . . . Repeats*>> text is, you will not know what to even "Ask".
So as you study and try to mimic the examples on the following pages, keep the above in mind. We recommend that you don't even try to create the <<*Ask*>> commands until you have thoroughly composed and tested your document. Remember that <<*Ask. . .*>>, <<*If* . . .>> and <<*Set* . . .>> commands are optional, so you certainly don't need them in the initial stages of source document development.
NOTE: Regardless of placement, each <<*Ask*. . .>> and <<*Set* . . .>> command must be on a separate line.
Benefits of <<*Ask*>> commands:
You can create better questions for the end users. (A typical Options block may or may not contain an answer that is sufficiently descriptive. Sometimes the Options block is simply "<<*Options(radio)*!Client!*him/her/them>>". The choice presented to the end user is, therefore, "him" "her" and "them" with a reference to "Client" in the Group box at the top of the selection screen. The <<*Ask*>>command can read something like "<<*AskOptions(radio)*!Client!Our client is a male/Our client is a female/Our client is more than one person*>>") (See 'Hover Over' text below for even more functionality.)
The experienced user will observe that any <<*Options*>> block (including the one above) can be set up to provide the identical prompts as may be provided in the <<*Ask*>> command. While true, we still recommend the use of the <<*Ask*>> command. Here are several reasons why:
When you add prompts to an <<*Options*>> block, the amount of 'real estate' it consumes can be substantial. When that block appears in the middle of a paragraph, it can be difficult to visually process (both to the editor and the end user who may peruse the document before processing it.)
There is something intangibly better about compositional questions being at the top of, and segregated from the body of, the main text.
Best reason: Once you have your 'best' questions composed and residing nicely within one of your documents, you can copy and paste an entire collection of <<*Ask*>> commands into any other document containing similar <<*Options/Optional*>> blocks. This assures a consistency in the questions that are posed to the end user.
For documents-by-building-block aficionados, you can also save the AskTable as a separate clause, calling it in along with other clauses to build, and then process, the document.
Try that with other programs!
Hover-Over text: In addition to 'prompt' text that will appear on each 'choice button' on the screen which presents the various options, you can provide up to 256 more characters of 'hover-over' text for each choice presented. This hover-over text will appear when the user moves the cursor over each choice. It will display only during the time the cursor is 'hovering over' the selection. To add hover-over text, simple type a '+' sign at the end of the prompt text and then type the hover-over text. Make sure the hover-over text is within the administrative section of Options block (i.e., before the third asterisk).
Click the button in the menu bar to read more about <<*Ask. . .*>> commands.