BSL:Grouping

This page and its subpages are used by templates to construct links and tables on BSL function and variable pages, the scripting task pages, and the list of all built-in functions and variables. The "meat" of the documentation of BSL's built-in functions/variables (we'll collectively call these "commands") are the scripting task pages, which are also known as "grouped" pages. These pages show the listing for each command (including the kind(s) of data that it takes or returns), and provide a contextual explanation of the use of this command in relation to other similar commands. A complex system of templates carries this information around the wiki in order to prevent having to enter information in duplicate or triplicate.

Detailed overview

First, a page is created with the name of a command, e.g. ai2_allpassive. This "command page" contains only a call which supplies information about a command to the BSLjunc template, which we can call a "junction template" in the sense that it provides a "railroad switch" between three formats of output, which we could call "single listing", "group listing", and "table entry". The single listing mode is the output that you see on the actual command page itself. Very similar to this is the output that you see on grouped pages. A grouped page is a page which groups together commands that relate to a single subject, such as BSL:AI activity. The third kind of output is wiki markup for an entry in a table. The table format is seen both at the top of grouped pages and on the BSL List page.

How does information entered once on a command page end up in four places across three kinds of pages? The answer lies in the fact that templates are not a unique kind of page. Transclusion syntax, including the passing in of parameters, can be used to "call" any kind of page as a template. Thus we can transclude command pages onto other pages, and we can even pass input to these pages when transcluding them in order to tell them what kind of output to give us, just like with a template. Each grouped page thus transcludes a command page amid the general documentation on that page, in order to get the command listing to appear just as it does on the command page (with the one difference of the message that accompanies each command; on the command page, it directs you to the grouped page, and on the grouped page, it provides a link to the command page).

There is further automation which allows us to automatically request on a grouped page that all commands in that group appear in the table at the top. This prevents having to list each command at the top of each page besides already transcluding each command in the body of the article, and also provides a guide as to which commands should actually be documented on the page. A similar table is built on the BSL List page using the same method. But how does a grouped page know which commands belong on that page, and how does a command page know what grouped page to link to? The grouping information comes from this very page and its subpages -- unlike the specific information about each command, which comes from the command pages.

Here's the complete flow of information, including most of the utility templates that provide support:

Command information

Information needed to list the command in full or table form is entered as part of the call to BSLjunc on the command page. Besides the essential information about the command, this template call also passes two parameters to the template which might be passed in to the command page itself. When the page is being viewed directly, there are no parameters being passed in. When it is transcluded, one or both parameters might be supplied to it and thus passed automatically on to BSLjunc. One parameter is "group", which is not needed for the output format that the command page is requesting for itself, so it doesn't matter that it has no value as part of the "single listing" view on the command page. The second parameter is "tableform", which has a default value of "no" which can be overridden by assigning a value to this parameter when the command page is "called" from another page. This is the secret to allowing the command page to switch between providing table output and listing output of the same set of information.

The next section will discuss how the command pages are called. First we'll consider how BSLjunc works. If "tableform" is overridden by a call to the command page which sets it to "yes", then the template BSLtableinfo is called upon to provide table markup for a single row which conveys the essentials about the command, fit for displaying in tables on the grouped pages and BSL List. If "tableform" is "no", then BSLjunc appraises whether it is being used on a command page or in the body of a grouped page article. It does this by comparing the current page name to the name of the command that is specified in the "name" parameter.

If the strings match, then a message is printed above the command info output that you are viewing a single listing and can view the command in the proper context by clicking on the link to the grouped page (the manner in which the link to the grouped page is generated is also described in the next section). If they do not match, then the assumption is made that the command is being viewed in a listing on a grouped page, and a message is displayed which allows the reader to jump to the command page so he can edit the information if something needs to be corrected or updated.

Then (getting to the main point of determining whether we are in listing or table mode), the template looks at whether the "kind" of the command is "func" or "var" and calls either BSLfuncinfo or BSLvarinfo, passing through the information that was passed to BSLjunc by the call made on the command page. These templates use table markup (with invisible borders so it doesn't look like a table) to create a nicely-laid out presentation for the command information.

Grouping information

The categorization of commands into groups takes place starting with the data entered on this grouping page. Note the key difference between the terms "grouping page" and "grouped page", which is that grouping pages are where grouping information is manually entered, to be utilized by command pages, grouped pages, and BSL List through templates. Below are the command groups, which are also the names of scripting task pages (with the BSL: prefix). This information is read by two different sets of templates.

First, when BSLjunc wants to display a message with the name of a command's group, it calls the Find BSL Group template to search every grouping page (the subpages of this very page) for the name of the command. Now, this template utilizes Foreach, and as explained on that template page, the number of calls that Foreach should make depends on how many items will be found when the page is parsed. There's no function that we can use to count commas in advance, so we have to manually embed that number directly in the page. That's why, if you scroll down to the bottom of this page, the number of command groups comes before the actual names of the command groups; that element is read in first and passed to Foreach, which passes that many of the page's group names to the specified template.

The second use for grouping information is when building tables. Each grouped page calls BSL Group Table, which looks for a grouping page by the same name as the page that called it. So if "BSL:AI activity" is calling the template, BSL Group Table looks for "BSL:Grouping/AI activity". If it exists, Foreach is used to pass each command name on that grouping page to the BSL Group Table Entry template, which simply calls (transcludes) the command page by that name while passing it "yes" for the "tableform" parameter (discussed above), and supplying the name of the group to which the command belongs. That group name will get used by BSLjunc for the "Group" column of the table for which it is providing table row markup.

Thus, a grouped page can construct a table with a single direct call to a template. BSL List uses a similar approach to constructing its complete table, except that it needs to list the commands in every group, not just one, so it uses Foreach to call BSL Group Table for every group name that is listed below on this page (actually it uses Foreach2, which is a duplicate of Foreach; this is because Foreach is already being used to perform the inner loop that processes every command name in a single group, and MediaWiki freaks out about a "template loop" if a template calls itself).

Summary

In short, you should edit these pages to change this information:

Altering grouping

• To change the names of the groups of commands, edit BSL:Grouping (that is, the data under the line below), but make sure that a page by each name exists under BSL:Grouping. Update the leading count if adding/removing groups.
• To change the membership of a command from one group to another, edit the BSL:Grouping subpages, and update the leading count on the two affected pages.

Altering command info

• To update the actual information about a command, edit the individual page for the function or variable.
• To explain how to use a BSL function or variable, or to compare the various related commands on the page, edit the scripting task pages. You are expected to manually transclude the commands by name onto this page so that you have control over the layout of the commands as part of an overall discussion.

Altering tables

• To change the tables at the top of the scripting task pages, you have to edit the grouping page of the same name, e.g. edit BSL:Grouping/AI activity as described under "Altering grouping" in order to affect the table on BSL:AI activity.
• To change the table on BSL:List, you have to edit the BSL:Grouping data below and the subpages under "BSL:Grouping", as described under "Altering grouping".

---

38,AI activity,AI affiliation,AI awareness,AI debugging,AI skills,AI tasks,Animation debugging,Animation playback,Animation recording,Character appearance,Character focus,Character health,Character movement,Character physics,Character position,Cinematic controls,Combat settings,Console management,Corpse management,Door management,Environmental objects,Game debugging,Game status,Geometry debugging,Graphics settings,HUD management,Input settings,Inventory management,Obsolete commands,Particle management,Script debugging,Sound debugging,Sound playing,Text output,Trigger laser management,Trigger volume management,Turret management,Weapon physics