Item10121: document the fact that revisions (1) may not start at 1 (2…

…) need not be sequential (3) must be positive, non-zero integers. And if you didn't know that, then it's about time you did.

git-svn-id: http://svn.foswiki.org/trunk@10220 0b4bb1d4-4e5a-0410-9cc4-b2b747904278

core/data/System/CommandAndCGIScripts.txt

@@ -53,6 +53,8 @@ All the scripts accept a number of common parameters. The first two components o
 | =user= | Command-line only; set the name of the user performing the action. Note: this usage is inherently insecure, as it bypasses webserver login constraints. For this reason only authorised users should be allowed to execute scripts from the command line. | |
 | =validation_key= | part of cross-site scripting protection. Any request sent from browsers that might change data stored on the server must carry a key that indentifies the source of the request. | |
 
+Where revision parameters are required, individual versions are identified by positive, non-zero integers. Older revisions always have lower numbers, but numbers cannot be assumed to be sequential, nor can the first version of a topic be assumed to be version 1. For compatibility reasons, Some scripts accept revision numbers with '1.' (or even 'r1.') prepended to the number, but this usage is deprecated and should be corrected when encountered.
+
 ---+++ =attach=
 Despite the name, this script doesn't actually attach a file to a topic - for that, use =upload=. This script is part of the transactions sequence executed when a file is uploaded from the browser. it just generates the "new attachment" page for a topic.
 

core/data/System/QuerySearch.txt

@@ -80,8 +80,8 @@ Fields in this plan are referenced using a simple _field specifier_ syntax:
 | =X[N]= | where =X= is an array and =N= is an integer number >= 0, gets the Nth element of the array =X=. If N is a floating point number, the integer part will be used as the index. Negative indices can be used to index the array from the end e.g. =attachments[-1]= to get the last attachment. | =attachments[3]= |
 | =X/Y= | accesses =Y= from the topic specified by the _value_ of =X=. =X= must evaluate to a topic name | =parent.name/(form.name='ExampleForm')= will evaluate to true if (1) the topic has a parent, (2) the parent topic has the main form type =ExampleForm=. |
 | ={X}= | expands to the value of the =configure= setting {X}, if it is accessible, or '' otherwise | only some configuration settings are available: %FORMAT{"%QUERY{"{AccessibleCFG}"}%" type="string" format="=$item=" separator=", "}% |
-| =X@Y= | Loads version Y of topic X. By default only the latest version of a topic is referenced, but this operator lets you refer to a specific historical version. Both X and Y may be arrays. If Y is the empty array =()=, will load all revisions of the topic. | ='Minutes.BoardOfDirectors'@(1).Attendees= will get the value of the 'Attendees' field in version 1 of that topic. Note the use of brackets to prevent the '.' being interpreted as part of a decimal number. | 
-| =@Y= | As =X@Y=, but refers to versions of the current topic. Equivalent to ='%<nop>WEB%.%<nop>TOPIC%'@Y= | ='GoreVidal' in @().info.author= will tell you if !GoreVidal ever edited the current topic. =@(1).form.name= will tell you the name of the form that was attached to revision 1 of the current topic. |
+| =X@Y= | Loads version Y of topic X. By default only the latest version of a topic is referenced, but this operator lets you refer to a specific historical version. Y is a positive integer, or an array of positive integers. If Y is the empty array =()=, will load all revisions of the topic. X may also be an array, allowing you to extract multiple versions of multiple topics. | ='Minutes.BoardOfDirectors'@(104).Attendees= will get the value of the 'Attendees' field in version 104 of that topic. Note the use of brackets to prevent the '.' being interpreted as part of a decimal number. | 
+| =@Y= | As =X@Y=, but refers to versions of the current topic. Equivalent to ='%<nop>WEB%.%<nop>TOPIC%'@Y= | ='GoreVidal' in @().info.author= will tell you if !GoreVidal ever edited the current topic. =@(31).form.name= will tell you the name of the form that was attached to revision 31 of the current topic. |
 
 Note: at some point Foswiki may support multiple forms in the same topic. For this reason you are recommended *not* to use the =fields= shortcut when accessing form fields, but always use the name of the form instead.
 

core/data/System/TopicsAndWebs.txt

@@ -26,6 +26,7 @@ Each topic has:
       * use WikiSyntax (see TextFormattingRules) and [[Macros][macros]] to write rich topic content
    * [[FileAttachment][attachments]]
       * topics may have one or more file attachments
+      * changes to attachments are automatically recorded
    * [[DataForms][DataForm]]
       * topics may have a [[DataForms][DataForm]] attached to them, which specifies [[MetaData][metadata]] fields that users may fill. This data may be [[QuerySearch][queried]] and [[FormattedSearch#Table_showing_form_field_values_of_topics_with_a_form][reported]] (see the [[FrequentlyAskedQuestions]] application as an example)
    * [[AccessControl][access controls]]
@@ -90,6 +91,13 @@ Note that if you use the [[WebCreateNewTopic][Topic Creator]], WikiWord rules ar
 
 <blockquote class="foswikiHelp">%I% The naming rules may be different for your installation; ask the [[mailto:%WIKIWEBMASTER%][wiki administrator]] who may have customised the ={NameFilter}= expert option under =Security and Authentication= in [[%SCRIPTURLPATH{"configure"}%#Environment$SecurityAndAuthentication][configure]]</blockquote>
 
+---+++ Revision numbers
+Topic and attachment versions are identified by positive, non-zero, integer numbers. Older revisions always have smaller numbers, but numbers cannot be assumed to be sequential, nor can you assume that the first revision of a topic will be revision 1. For example, you might have a topic history that runs like this:
+
+=84 > 95 > 1001 > 7690=
+
+where 84 is the first version and 7690 the most recent.
+
 #RenamingTopics
 #RevisionRollback
 ---+++ Reverting, renaming, moving and deleting topics

core/data/System/VarREVINFO.txt

@@ -10,22 +10,22 @@
       * Expands to: <code>%REVINFO%</code>
    * Supported parameters:
      | *Parameter:* | *Description:* | *Default:* |
-     | ="format"= | Format of revision information, see supported formatting tokens below | ="r1.$rev - $date - $wikiusername"= |
+     | ="format"= | Format of revision information, see supported formatting tokens below | ="r$rev - $date - $wikiusername"= |
      | =web="..."= | Name of web | Current web |
      | =topic="..."= | Topic name | Current topic |
-     | =rev="1.5"= | Specific revision number | Latest revision |
+     | =rev="5"= | Specific revision number | Latest revision |
    * Supported formatting tokens:
      | *Token:* | *Unit:* | *Example* |
      | =$web= | Name of web | Current web |
      | =$topic= | Topic name | Current topic |
-     | =$rev= | Revision number. Prefix =r1.= to get the usual =r1.5= format | =5= |
+     | =$rev= | Revision number. | =5= |
      | =$username= | Login username of revision | =jsmith= |
      | =$wikiname= | WikiName of revision | =JohnSmith= |
      | =$wikiusername= | <nop>WikiName with %USERSWEB% web prefix | =%USERSWEB%.JohnSmith= |
      | =$date= | Revision date. Actual date format defined as {DefaultDateFormat} in [[%SCRIPTURLPATH{"configure"}%][configure]] | =21 Sep 2006= |
      | =$time= | Revision time | =23:24:25= |
      | =$iso= | Revision date in ISO date format | =2006-09-22T06:24:25Z= |
      | =$min=, =$sec=, etc. | Same date format qualifiers as [[%IF{"'%INCLUDINGTOPIC%'='Macros'" then="#"}%VarGMTIME][GMTIME{"format"}]] | |
-   * Example, returns revision info of first revision: <verbatim class="tml">%REVINFO{"$date - $wikiusername" rev="1.1"}%</verbatim> 
+   * Example, returns revision info of revision 43: <verbatim class="tml">%REVINFO{"$date - $wikiusername" rev="43"}%</verbatim> 
    * Related: [[%IF{"'%INCLUDINGTOPIC%'='Macros'" then="#"}%VarGMTIME][GMTIME{"format"}]], [[%IF{"'%INCLUDINGTOPIC%'='Macros'" then="#"}%VarREVINFO][REVINFO]]
 <!--%JQREQUIRE{"chili"}%-->