Custom statement content


#1

All examples of custom statements in both Pan6 and PanX show the parameter name and type definitions in upper case, as in

<parameter NAME=FIRSTNUM TYPE=TEXT> The first number. </parameter >
< parameter NAME=SECONDNUM TYPE=TEXT> The second number. </parameter >
< parameter NAME=TOTALNUM TYPE=TEXT> The sum of the two numbers. </parameter >

In fact, in both versions, a custom statement works fine if all of this is in lower case. Is there a reason to use upper case (I’m primarily concerned with PanX)?

There are several new tag sets in PanX procedure info blocks, and I’m confused as to what values to enter into the and , tags of a new statement. Their format and purpose is clear but there appears to be little consistency across existing entries with considerable variation occurring even between a statement and its function - see arrayfilter and arayfilter( for example. It looks to me like a good idea that got out of its cage and is now running wild. Are there any guidelines for their content or do we just try to make the entries as meaningful and useful as possible?

My understanding is that we should use only the following tags in a procedure info block and that the tags should not include chevrons:

<procedureinfo>
<description>
<breadcrumb>
<tags>
<parameter>
<body>
<errors>
<seealso>
<history>

Is that correct?

michael


#2

I don’t remember. But I always do use upper case. I’m pretty sure I originally had a reason, but I’m not sure if it is still necessary or not.

How would you know? The tags are mostly only used once, when I intake the information into a database. So it is a procedure in that database that processes the tags. That database only exists on my development computer – it is not the Help database that comes with Panorama (though it generates the data for the Help database).

Actually, Panorama does look at this block when it is registering custom statements – but all it does is count the number of parameters. It does not care what the actual names are. So yes, I’m sure it can do that whether the information is upper or lower case. But I’m not sure about the help system intake. Probably best to use upper case to be safe.


In your examples, the tags contains spaces. I don’t think that will work.

You should not use chevrons.

I suppose you could put other tags in, but they will be ignored. Your list looks correct.

Part of your post is garbled, so I didn’t answer that.


#3

I don’t believe I gave any tag examples but, anyway, I do know not to include spaces.

I’ve no idea what the garbled bit was - you answered all my questions. Thanks Jim

michael


#4

Your examples had spaces after the < and before the >

< parameter
</parameter >

You said

 I'm confused as to what values to enter into the and , tags of a new statement

seems like something was missing there (I think you forgot to put the backticks around the tags), but if I answered all the questions, great!


#5

Right - the missing bit was asking if there were established lists of approved entries for Breadcrumb and Tags content - there appears to be little consistency, even across a statement and its matching function (eg., see the arrayfilter entries in Help). I think I described the entries as a good idea that had escaped its restraints.

m


#6

The idea of the <breadcrumb> tag is to give a hierarchical (tree) structure to the help system. The idea is that there would be topics, subtopics, sub-subtopics, etc. down to the lowest level (the “leaves” of the tree). So as an example, the part of the tree related to the upper( function might look like this.

Panorama
  Formulas
    Text
      String Modification
        upper( function

The problem is, for the most part, so far I have only written the leaves, and almost none of the branches or trunks. So in the meantime, I’ve been filling in the breadcrumbs with what I expect the names of these branches or trunks will be. I’m sure these will need to be adjusted when this pages actually get written (many of these pages will be adaptations from the Panorama 6 Formulas & Programming book).

The <tags> tag works with see also. If you put @tagname into the <seealso> tag, it will automatically include every topic that has that tagname into the see also list. Not only does this mean that each topic doesn’t have to be individually listed in the see also section, it also means that as new topics are created, they will automatically be added to the appropriate see also areas if they have the correct tag. This could use some fine tuning – in some cases way too many topics are being listed, but I think it is a good first approximation and much better than no see also links at all.