Subdirectories

doc/source/general/volumes.rst

@@ -4,20 +4,12 @@
 Files and Volumes
 =================
 
-Using the COPY, SWITCH, DELETE, and RENAME commands, you can manipulate the archive and the volumes as described in the :ref:`File I/O page <files>`. But before you do that, it's useful to know how kOS manages the archive and the volumes, and what they mean.
+Using the COPYPATH, SWITCH, DELETEPATH, and RENAMEPATH commands, you can manipulate the archive and the volumes as described in the :ref:`File I/O page <files>`. But before you do that, it's useful to know how kOS manages the archive and the volumes, and what they mean.
 
 .. contents::
     :local:
     :depth: 2
 
-.. warning::
-
-    .. versionchanged:: 0.15
-
-        **Archive location and file extension change**
-
-        The Archive where KerboScript files are kept has been changed from ``Plugins/PluginData/Archive`` to ``Ships/Script``, but still under the top-level **KSP** installation directory. The file name extensions have also changes from ``.txt`` to ``.ks``.
-
 Script Files
 ------------
 
@@ -53,7 +45,7 @@ program on it. To simulate the sense that this game takes place at the
 dawn of the space race with 1960's and 1970's technology, the storage
 capacity of a volume is very limited.
 
-For example, the CX-4181 Scriptable Control System part defaults to only 
+For example, the CX-4181 Scriptable Control System part defaults to only
 allowing 1000 bytes of storage.
 
 The byte count of a program is just the
@@ -99,8 +91,7 @@ volume inside it.
 If you have multiple CX-4181 parts on the same craft, they are assumed
 to be networked together on the same system, and capable of reading each
 other's hard drives. Their disk drives each have a different Volume, and
-by default they are simply numbered 1,2,3, … unless you rename them with
-the RENAME command.
+by default they are simply numbered 1,2,3, … unless you rename them.
 
 For example, if you have two CX-4181's on the same craft, called 1 and
 2, with volumes on them called 1 and 2, respectively, it is possible for
@@ -116,11 +107,13 @@ different CPUs. The same volume which was called '2' when one CPU was
 looking at it might instead be called '1' when a different CPU is
 looking at it. Each CPU thinks of its OWN volume as number '1'.
 
-Therefore using the RENAME command on the volumes is useful when dealing
+Therefore using the SET command on the volumes is useful when dealing
 with multiple CX-4181's on the same vessel, so they all will refer to
-the volumes using the same names.
+the volumes using the same names::
+
+  SET VOLUME("0"):NAME TO "newname".
 
-If a kOS processor has a name tag set, then that processor's volume 
+If a kOS processor has a name tag set, then that processor's volume
 will have its name initially set to the value of the name tag.
 
 Archive
@@ -164,3 +157,35 @@ volume but with the following exceptions:
    constitutes a form of cheating similar to any other edit of the
    persistence file.
 
+.. _boot:
+
+Special handling of files in the "boot" directory
+-------------------------------------------------
+
+For users requiring even more automation, the feature of custom boot scripts
+was introduced. If you have at least 1 file in the :code:`boot` directory on
+your Archive volume, you will be presented with the option to choose one of
+those files as a boot script for your kOS CPU.
+
+.. image:: http://i.imgur.com/05kp7Sy.jpg
+
+As soon as you vessel leaves VAB/SPH and is being initialised on the launchpad
+(e.g. its status is PRELAUNCH) the assigned script will be copied to CPU's
+local hard disk with the same name.  If kOS is configured to start on the
+archive, the file will not be copied locally automatically. This script will
+be run as soon as CPU boots, e.g. as soon as you bring your CPU in physics
+range or power on your CPU if it was turned off.  You may get or set the name
+of the boot file using the :attr:`kOSProcessor:BOOTFILENAME` suffix.
+
+Important things to consider:
+
+  * kOS CPU hard disk space is limited, avoid using complex boot scripts or increase disk space using MM config.
+  * Boot script runs immediately on initialisation, it should avoid interaction with parts/modules until physics fully load. It is best to wait for couple seconds or until certain trigger.
+
+Possible uses for boot scripts:
+
+  * Automatically activate sleeper/background scripts which will run on CPU until triggered by certain condition.
+  * Create basic station-keeping scripts - you will only have to focus your probes once in a while and let the boot script do the orbit adjustment automatically.
+  * Create multi-CPU vessels with certain cores dedicated to specific tasks, triggered by user input or external events (Robotic-heavy Vessels)
+  * Anything else you can come up with
+

doc/source/structures/volumes_and_files/path.rst

@@ -0,0 +1,144 @@
+.. _path:
+
+Path
+====
+
+Represents a path. Contains suffixes that can be helpful when using and manipulating paths. You can use
+:ref:`path() <path_command>` to create new instances.
+
+Instances of this structure can be passed as arguments instead of ordinary, string paths, for example::
+
+  copypath("../file", path()).
+
+.. structure:: Path
+
+    .. list-table::
+        :header-rows: 1
+        :widths: 2 1 4
+
+        * - Suffix
+          - Type
+          - Description
+
+        * - :attr:`VOLUME`
+          - :struct:`Volume`
+          - Volume this path belongs to
+        * - :attr:`SEGMENTS`
+          - :struct:`List` of :struct:`String`
+          - List of this path's segments
+        * - :attr:`LENGTH`
+          - :struct:`Scalar`
+          - Number of segments in this path
+        * - :attr:`NAME`
+          - :struct:`String`
+          - Name of file or directory this path points to
+        * - :attr:`HASEXTENSION`
+          - :struct:`Boolean`
+          - True if path contains an extension
+        * - :attr:`EXTENSION`
+          - :struct:`String`
+          - This path's extension
+        * - :attr:`ROOT`
+          - :struct:`Path`
+          - Root path of this path's volume
+        * - :attr:`PARENT`
+          - :struct:`Path`
+          - Parent path
+        * - :meth:`CHANGENAME(name)`
+          - :struct:`Path`
+          - Returns a new path with its name (last segment) changed
+        * - :meth:`CHANGEEXTENSION(extension)`
+          - :struct:`Path`
+          - Returns a new path with extension changed
+        * - :meth:`ISPARENT(path)`
+          - :struct:`Boolean`
+          - True if `path` is the parent of this path
+        * - :meth:`COMBINE(name1, [name2, ...])`
+          - :struct:`Path`
+          - Returns a new path created from this one
+
+.. attribute:: Path:VOLUME
+
+    :type: :struct:`Volume`
+    :access: Get only
+
+    Volume this path belongs to.
+
+.. attribute:: Path:SEGMENTS
+
+    :type: :struct:`List` of :struct:`String`
+    :access: Get only
+
+    List of segments this path contains. Segments are parts of the path separated by `/`. For example path `0:/directory/subdirectory/script.ks` contains the following segments:
+    `directory`, `subdirectory` and `script.ks`.
+
+.. attribute:: Path:LENGTH
+
+    :type: :struct:`Scalar`
+    :access: Get only
+
+    Number of this path's segments.
+
+.. attribute:: Path:NAME
+
+    :type: :struct:`String`
+    :access: Get only
+
+    Name of file or directory this path points to (same as the last segment).
+
+
+.. attribute:: Path:HASEXTENSION
+
+    :type: :struct:`Boolean`
+    :access: Get only
+
+    True if the last segment of this path has an extension.
+
+.. attribute:: Path:EXTENSION
+
+    :type: :struct:`String`
+    :access: Get only
+
+    Extension of the last segment of this path.
+
+.. attribute:: Path:ROOT
+
+    :type: :struct:`Path`
+    :access: Get only
+
+    Returns a new path that points to the root directory of this path's volume.
+
+.. attribute:: Path:PARENT
+
+    :type: :struct:`Path`
+    :access: Get only
+
+    Returns a new path that points to this path's parent. This method will throw an exception if this path does not have a parent (its length is 0).
+
+.. method:: Path:CHANGENAME(name)
+
+    :parameter name: :struct:`String` new path name
+    :return: :struct:`Path`
+
+    Will return a new path with the value of the last segment of this path replaced (or added if there's none).
+
+.. method:: Path:CHANGEEXTENSION(extension)
+
+    :parameter extension: :struct:`String` new path extension
+    :return: :struct:`Path`
+
+    Will return a new path with the extension of the last segment of this path replaced (or added if there's none).
+
+.. method:: Path:ISPARENT(path)
+
+    :parameter path: :struct:`Path` path to check
+    :return: :struct:`Boolean`
+
+    Returns true if `path` is the parent of this path.
+
+.. method:: Path:COMBINE(name1, [name2, ...])
+
+    :parameter name: :struct:`String` segments to add
+    :return: :struct:`Path`
+
+    Will return a new path created by adding segments to this path.