How to combine function descriptions

This provides guidelines for moving the Analytica Tutorial, User Guide, and Optimizer from Framemaker (or PDF) into the Analytica wiki in Mediawiki format.

Guide for integrating Function descriptions

The User Guide and Analytica wiki often contain partially overlapping information about each function (and other features). Usually, the User Guide has a clearer introductory description and often better examples for common cases, and is better edited, but the wiki page has more details and reference material, especially on recently added or more obscure parameters and features. The trick is to integrate the information from the two sources into a single page that it is easy to read, retains all key information, and avoids duplication.

Usually, each function has (or should have) its own wiki page. In a fwe cases, two or more closely related functions share a page -- e.g.

           = Cdf and Pdf Functions =

When moving the description of each function from the User Guide, you should copy it into the existing wiki page for that function, rather than creating a new page (or leaving it in a section of a parent page).

You may find it easiest to copy the material from the PDF document into the top of the existing wiki page for each function. The User Guide description is usually a better introduction, followed by clearer simple examples. After copying it in, you can review the material and remove duplicate material. Often you can use the new introduction simply to replace the existing introduction to the function. But, you should review the material carefully to make sure that the introduction in the wiki doesn't contain something important that isn't in the material from the User Guide.

The elements of a function description

Each function description page in the wiki should have a fairly standard format, including these elements. The first element page title is always a level 1 heading. The other elements should each use a level 2 subheading, e.g. in wiki markup:

== Uniform(min, max)==

Page title: The page title should always be the name of the function, without parameters -- e.g. Uniform, not "Uniform(a, b)". It is critical to capitalize the function name -- i.e. first letter uppercase and remaining letters lowercase. Mediawiki links are case sensitive, so it is important to use this convention consistently. The Page title appears in bold dark red in the standard format for this wiki.

Function call with main parameters: E.g. Uniform(min, max). This is a subhead that consists of the function with its main parameters. Many functions have a long string of optional parameters. This subhead should include only the first few, most commonly used parameters, omitting the later more obscure optional parameters. When in doubt, just use what is in the User Guide.

Introduction: The next section, usually a paragraph is a brief description of what the function does, including a mention of its most common parameters. You can usually use the introduction from the User Guide, unless the introduction in the wiki is obviously better. You don't actually need a subheading Introduction. This text just appears directly under the function call with main parameters.

Examples: Show one or two examples of most common usages.They may include a result table and/or graph. You don't actually need a subheading called Examples. This text just appears directly under the introduction text and function call with main parameters.

Library: Function descriptions in the User Guide usually contain this section with the name of the library containing this function. This is obsolete because the information is replaced by the Categories mechanism on the wiki (see below). After making sure the library is mentioned in the Categories, just delete this section (or just don't copy it from the User Guide).

Optional parameters: A list of the optional parameters, each on a separate line, followed by a phrase or paragraph explaining what each parameter is or does. Some may include example code and results to illustrate the use and effect of selected optional parameters.

Details & More Examples: If there is any more esoteric text or examples, they should go here.

History An optional section mentioning the Analytica release in which a new feature was introduced or modified. Many existing wiki pages have notations at the top or elsewhere saying things like “New to Analytica 4.3”. Please move such notations into this History section, since this information is of limited interest to most users. It's fine just to delete these notations for releases 4.4 and earlier.

See also: A list of links to pages with related functions, concepts, and examples. It's a good idea to include this even if it's currently empty. Please add links to any functions or concepts that are obviously related. Completing this may require an Analytica expert.

Category: Category is a Mediawiki mechanism that lets you specify one or more categories containing this function (or other feature). Mediawiki then creates Category pages with links to all the pages in that category. It also shows links to the Category page(s) from each page in that category. Most existing function pages in the wiki already contain a Categories section. As explained above, most function descriptions in the User Guide have a Library section specifying what library contains the function. This section should be replaced by putting the library name in the Categories list -- e.g.. if the User Guide description contains Library: Array functions replace that by

 [[Category:Array functions]]

The categories are listed at the bottom of the displayed page regardless of where the Category wiki code is in the source page.

Analytica Tables

Many code example results show tables. Usually, it best to show the example code, followed by →, which means "the result of evaluating this code is", followed by the actual result. If its a table, use a format like this. Columns should be spaced at 75px or so. Indexes should be bolded. Text should be aligned left.

MDTable(T, Rows, Cols, [Car_type, Mpg], 'average', 'n/a') →

	Mpg ▶
Car_type ▼	26	30	35
VW	2185	1705	n/a
Honda	2330	n/a	2210
BMW	n/a	2955	2835

Conventions

Subheads: The wiki often has “subheads” at same level as main page heading. They should all be one or more levels lower,e.g.
- == Subheading ==
- === Subsubheading ===
Parameters: Should match the software (which is not necessarily the same as the User Guide). Should always be lowercase, even when one letter. While the Use Guide often bolds parameters, the Wiki should use double angle brackets for «parameters» when referred to outside of the function. When referred to with a function, i.e. Sequence(start, end, step), then parameters should be in parentheses with spaces after each comma. In code when parameters are called by name (i.e. descending: True), there should be a space after the colon.
Functions: should be linked to like so [[Sequence]] except in headings and in code. When using parenthesis to denote parameters, there should not be a space between the function and the parentheses, i.e. Sequence(start, end, step).
Null should be linked: [[Null]]
Special Analytica Terms linked: [[Intelligent Array]], [[Attribute]]
Parameter Qualifier: should just be capitalized (i.e. Boolean, Array)
Variables: should be Bold and Capitalized; the User Guide identifies Analytica variables using fixed width, e.g. Destinations where the wiki often uses italic e.g. Destinations.

Example Pages

Function pages that have already been combined and cleaned. Page numbers are PDF page numbers, not document page numbers

Sequence - p 184 in User Guide
Sort - p 210 in User Guide
Sum - p203 in User Guide
Uniform - p 276 and 284 in User Guide