Resolving several github issues about documentation

doc/source/general/cpu_hardware.rst

@@ -26,49 +26,63 @@ Kerbal Space Program simulates the universe by running the universe in
 small incremental time intervals that for the purpose of this
 document, we will call "**physics ticks**". The exact length of time
 for a physics tick varies as the program runs. One physics tick might
-take 0.09 seconds while the next one might take 0.085 seconds. (The
-default setting for the rate of physics ticks is 25 ticks per second,
-just to give a ballpark figure, but you **must not** write any scripts
-that depend on this assumption because it's a setting the user can
-change, and it can also vary a bit during play depending on system
-load. The setting is a target goal for the game to try to achieve, not
-a guarantee. If it's a fast computer with a speedy animation frame
-rate, it will try to run physics ticks less often than it runs
-animation frame updates, to try to make the physics tick rate match
-this setting. On the other hand, If it's a slow computer, it will try
-to sacrifice animation frame rate to archive this number (meaning
-physics get calculated faster than you can see the effects.)
-
-When calculating physics formulas, you need to actually measure
-elapsed time in the TIME:SECONDS variable in your scripts.
+take 0.02 seconds while the next one might take 0.021 seconds and maybe
+the next one takes 0.019 seconds.
+
+The game *tries* to simulate the universe using 50 physics ticks per
+second (0.02 seconds per tick), but there is no guarantee it succeeds
+at this.  There is a lot of variation depending on how fast your
+computer is, and how heavily you are loading it with large rockets or
+complex mods.
+
+If the KSP game is unable to execute *physics ticks* fast enough to
+keep up the 50-per-second rate, that's when you see the time display
+in the upper-left of the Kerbal Space Program screen turn yellow or
+red as a warning that simulation is getting coarse-grain and might
+start getting error-prone because of it.
+
+The relevant take-away from that is this: When calculating physics
+formulas, never assume elapsed time moves in constant amounts.  It
+is *typically* about 0.02 seconds per physics tick, but not reliably
+so.  You need to actually measure elapsed time in the TIME:SECONDS
+variable in any formulas that depend on delta time.
 
 The entire simulated universe is utterly frozen during the duration of
 a physics tick. For example, if one physics tick occurs at timestamp
-10.51 seconds, and the next physics tick occurs 0.08 seconds later at
-timestamp 10.59 seconds, then during the entire intervening time, at
-timestamp 10.52 seconds, 10.53 seconds, and so on, nothing moves. The
-clock is frozen at 10.51 seconds, and the fuel isn't being consumed,
-and the vessel is at the same position. On the next physics tick at
-10.59 seconds, then all the numbers are updated.  The full details of
-the physics ticks system are more complex than that, but that quick
-description is enough to describe what you need to know about how
-kOS's CPU works.
-
+10.50 seconds, and the next physics tick occurs 0.02 seconds later at
+timestamp 10.52 seconds, then during all the intervening times, such
+as at timestamp 10.505 seconds, 10.51 seconds, and 10.515 seconds
+nothing has moved. ``TIME:SECONDS`` will claim the time is still 10.50
+seconds during that whole time, and the fuel isn't being consumed, and
+the vessel is at the same position. On the next physics tick at 10.52
+seconds, then all the numbers are updated.  The full details of the
+physics ticks system are more complex than that, but that quick
+description is enough to describe what you need to know about how kOS's
+CPU works.
+
+**Physics ticks are NOT your FPS:**
 There is another kind of time tick called an **Update tick**. It is
 similar to, but different from, a **physics tick**. *Update ticks*
 often occur a bit more often than *physics ticks*. Update ticks are
 exactly the same thing as your game's Frame Rate. Each time your game
-renders another animation frame, it performs another Update tick. On a
-good gaming computer with fast speed and a good graphics card, It is
-typical to have about 2 or even 3 *Update ticks* happen within the
-time it takes to have one *physics tick* happen. On a slower computer,
-it is also possible to go the other way and have *Update ticks*
-happening *less* frequently than *physics tics*. Basically, look at
-your frame rate. Is it higher than 25 fps? If so, then your *update
-ticks* happen faster than your *physics ticks*, otherwise its the
-other way around.
-
-It is important to note that versions of kOS prior to 0.17 executed program code during update ticks.  After that point, program code was executed during the physics ticks.
+renders another animation frame, it performs another Update tick. 
+Essentially, *physics ticks* get the first dibs on execution time,
+while *update ticks* use up whatever time is leftover after that.
+If your computer is super fast so there's a lot of leftover time
+after *physics ticks* are satisfied, it just uses that time to make
+more *update ticks*, not to make more *physics ticks*.  A fast
+computer might have 2 or 3 *update ticks* per *physics tick*.  A slow
+computer might only be able to manage 1 *update tick* per *physics
+tick*, or in extreme cases, less than 1 so animation is in fact
+painting the picture at a slower frame rate than the frame rate that
+the physical world is actually being simulated under the hood.
+
+It is important to note that versions of kOS prior to v0.17 executed
+program code during these *update ticks* so they were tied to your 
+animation FPS.  But versions more recent than that started executing
+code on *physics ticks*, as is more proper for the simulation, and
+to make script behvaior more consistent across different computers with
+different frame rates.
 
 .. _electricdrain:
 

doc/source/language/syntax.rst

@@ -23,13 +23,38 @@ operator symbols:
 
 .. highlight:: none
 
-**Arithmetic Operators**::
-
-    +  -  *  /  ^  e
-
-**Logic Operators**::
-
-    not  and  or  true  false  <>  >=  <=  =  >  <
+.. _operators:
+
+**Arithmetic Operators**: These are listed in order of precedence from first to last:
+
+    * ``(`` ..to.. ``)`` -> Grouping with brackets makes the expression evaluate first.
+    * ``e`` -> Scientific notation operator, for example: ``1.23e-4`` is ``0.000123``.
+    * ``^`` -> Exponent operator, for example: ``2^3`` is ``8``.
+    * ``*``, ``/`` -> Multiplication and Division, having equal precedence.  Note that
+      division never truncates remainders, even when given two integer operands.
+      (i.e. ``1 / 4`` will return ``0.25``, not ``0``).
+    * ``+``, ``-`` -> Addition and Subtraction, having equal precedence.
+
+**Logic Operators**: These are listed in order of precedence from first to last:
+
+    * ``(`` ..to.. ``)`` -> Grouping with brackets makes the expression evaluate first.
+    * ``not`` -> ``not A`` Logical inversion of A.  Due to the high precedence,
+      if A is some complex expression you may need to write this with brackets
+      as ``not(A)`` in kerboscript to make it parse right.
+    * ``=``, <>``, ``>=``, ``<=``, ``>``, ``<`` -> Comparitors.  Note
+      that equals and not-equals are different than in some common languages:
+         * The equals comparitor is a single character ``=`` not a double-equal ``==``.
+         * The not-equal comparitor is ``<>`` not ``!=``.
+    * ``and`` -> Logical AND of two Boolean expresssions.
+    * ``or`` -> Logical OR of two Boolean expresssions.
+
+** Logic constants**: all logic operators return one of these, and you may assign them to variables:
+
+    * ``false`` -> (case insensitive, so can be writtedn as False, FALSE, etc)
+    * ``true`` -> (case insensitive, so can be written as True, TRUE, etc)
+    * Although not a recommended programming style to use, numbers used in a
+      logic context get interpreted as Boolean values followng the typical
+      rule that zero is ``false`` and anything other than zero is ``true``.
 
 **Instructions and Keywords**::
 
@@ -41,7 +66,28 @@ operator symbols:
 
 **Other Symbols**::
 
-    ( )  {  }  [  ]  ,  :  #  @  //
+    * ``//`` -> Comment indicator - starts a comment that runs until
+      the end of the line.
+    * ``( )`` -> Used either to group expressions to change the order of
+      operations (in the usual fashion), or to mark the parameters of
+      a function being called, like ``min(a, b)``.
+    * ``{  }`` -> Used to group a list of statements together into a
+      single block of statements.  Used to define the beginning and
+      ending of a function body, loop body, or conditional body.
+    * ``[  ]`` -> Denotes a list index or lexicon index.
+    * ``#`` -> An archaic way to index lists that is mostly supplanted by
+      the ``[ ]`` square bracket operator, but exists for backward
+      compatibility.
+    * ``,`` -> Separates arguments when calling a function, or parameters
+      when defiing a function.
+    * ``:`` -> The suffix operator.  Indicates a suffix of an object is
+      coming next.  Similar to the dot operator in other languages for
+      denoting a member of an object.
+    * ``@`` -> Delegate operator.  Appended to a call-able identifier
+      such as a function name to suppress the usual compiler behavior
+      of trying to call the function as soon as the script mentions it.
+      "@" tells it to instead return a delegate of the function that
+      may be called later.
 
 .. highlight:: kerboscript
 

doc/source/math/geocoordinates.rst

@@ -48,6 +48,10 @@ Structure
 	  - Args
           - Description
 
+        * - :attr:`BODY`
+          - :ref:`body <body>` (m)
+	  - none
+          - The celestial body this geocoordinates is on.
         * - :attr:`LAT`
           - :ref:`scalar <scalar>` (deg)
 	  - none
@@ -93,9 +97,9 @@ Structure
 
     This type is serializable.
 
-.. attribute:: GeoCoordinates:LAT
+.. attribute:: GeoCoordinates:BODY
 
-    The latitude of this position on the surface.
+    The :ref:`Celestial Body <body>` this position is attached to.
 
 .. attribute:: GeoCoordinates:LNG
 

doc/source/structures/collections/iterator.rst

@@ -21,7 +21,7 @@ A loop using an :struct:`Iterator` on a :struct:`List` might look like this::
     SET MyCurrent TO MyList:ITERATOR.
     PRINT "before the first NEXT, position = " + MyCurrent:INDEX.
     UNTIL NOT MyCurrent:NEXT {
-        PRINT "Item at position " + MyIter:INDEX + " is [" + MyIter:VALUE + "].".
+        PRINT "Item at position " + MyCurrent:INDEX + " is [" + MyCurrent:VALUE + "].".
     }
 
 .. highlight:: none

doc/source/structures/collections/list.rst

@@ -64,6 +64,18 @@ Structure
         * - :meth:`JOIN(separator)`
           - :ref:`string <string>`
           - joins all list elements into a string
+        * - :meth:`FIND(item)`
+          - :ref:`scalar <scalar>`
+          - returns the first index of the item within the list
+        * - :meth:`INDEXOF(item)`
+          - :ref:`scalar <scalar>`
+          - Alias for :meth:`FIND(item)`
+        * - :meth:`FINDLAST(item)`
+          - :ref:`scalar <scalar>`
+          - returns the last index of the item within the list
+        * - :meth:`LASTINDEXOF(item)`
+          - :ref:`scalar <scalar>`
+          - Alias for :meth:`FINDLAST(item)`
 
 .. note::
 
@@ -117,6 +129,35 @@ Structure
 
     Returns a string created by converting each element of the array to a string, separated by the given separator.
 
+.. method:: List:FIND(item)
+
+    :parameter item: (any type) the item to attempt to find within the list
+    :return: :struct:`Scalar`
+
+    Returns the first integer index within the list where an item equal to
+    this item can be found.  Whatever the definition of "equals" is for this
+    item type will be used to decide if a match is found.  This is a linear
+    search from start to finish so it can be slow if the list is long.
+
+    If no such item is found, a ``-1`` is returned.
+
+.. method:: List:INDEXOF(item)
+
+    This is just an alias for :meth:`FIND(item)`.
+
+.. method:: List:FINDLAST(item)
+
+    :parameter item: (any type) the item to attempt to find within the list
+    :return: :struct:`Scalar`
+
+    This is the same as :meth:`FIND(item)`, except that it searches
+    backward instead of forward through the list.  It finds the lastmost
+    element that is equal to the item.
+
+.. method:: List:LASTINDEXOF(item)
+
+    This is just an alias for :meth:`FINDLAST(item)`.
+
 Access to Individual Elements
 -----------------------------
 

doc/source/structures/misc/string.rst

@@ -246,6 +246,11 @@ Structure
 
     Returns the index of the first occurrence of the given string in this string (starting from 0).
 
+    If the ``string`` passed in is not found, this returns -1.
+
+    If the ``string`` passed in is the empty string ``""``, this always claims to have
+    successfully "found" that empty string at the start of the search.
+
 .. method:: String:FINDAT(string, startAt)
 
     :parameter string: :struct:`String` to look for
@@ -254,13 +259,23 @@ Structure
 
     Returns the index of the first occurrence of the given string in this string (starting from startAt).
 
+    If the ``string`` passed in is not found, this returns -1.
+
+    If the ``string`` passed in is the empty string ``""``, this always claims to have
+    successfully "found" that empty string at the start of the search.
+
 .. method:: String:FINDLAST(string)
 
     :parameter string: :struct:`String` to look for
     :type: :struct:`String`
 
     Returns the index of the last occurrence of the given string in this string (starting from 0)
 
+    If the ``string`` passed in is not found, this returns -1.
+
+    If the ``string`` passed in is the empty string ``""``, this always claims to have
+    successfully "found" that empty string at the beginning of the search.
+
 .. method:: String:FINDLASTAT(string, startAt)
 
     :parameter string: :struct:`String` to look for
@@ -269,6 +284,11 @@ Structure
 
     Returns the index of the last occurrence of the given string in this string (starting from startAt)
 
+    If the ``string`` passed in is not found, this returns -1.
+
+    If the ``string`` passed in is the empty string ``""``, this always claims to have
+    successfully "found" that empty string at the beginning of the search.
+
 .. method:: String:INDEXOF(string)
 
     Alias for FIND(string)