From 5d48ca4ffa2fd31c3ae76505c030c5f0735c2c18 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Thu, 28 Jul 2022 23:19:41 -0500 Subject: [PATCH] Update: Fixes, improvements, and add additional specifications and documentation. A number of website mistakes are fixed. Tweak the styling some. Implement a "highlight" class rather than hard-coding the highlighting of the menu entries against "unlink". Add numerous specification and documentation pages. This is a manual process because I have yet to implement an auto-generator script for this. I have not determined the style practice as well. I also reached some burn-out while writing this and started working faster and sloppier. The result is a rather inconsistent mix of the HTML markup transcription of the specifications and documentation. Due to being a bit sloppier near the end, I also expect several mistakes in the transcription process. I did not get to the Featureless Make specifications and documentation within the scope of this commit. --- css/kevux.css | 7 + distributions/turtle/changelog.html | 2 +- distributions/turtle/documentation.html | 2 +- distributions/turtle/documentation/additional.html | 4 +- .../turtle/documentation/configuring.html | 2 +- distributions/turtle/documentation/credits.html | 2 +- distributions/turtle/documentation/installing.html | 2 +- distributions/turtle/documentation/problems.html | 5 +- distributions/turtle/documentation/running.html | 2 +- distributions/turtle/documentation/servers.html | 2 +- distributions/turtle/documentation/software.html | 2 +- documentation.html | 14 +- documentation/byte_dump.html | 36 +- documentation/byte_dump/specifications.html | 95 +++ documentation/control.html | 39 +- documentation/control/specifications.html | 115 ++++ .../control/specifications/packet_request.html | 158 +++++ .../control/specifications/packet_response.html | 203 ++++++ documentation/control/specifications/settings.html | 229 +++++++ documentation/controller.html | 200 ++++-- documentation/controller/specifications.html | 132 ++++ .../controller/specifications/action.html | 222 +++++++ documentation/controller/specifications/entry.html | 704 +++++++++++++++++++++ documentation/controller/specifications/exit.html | 648 +++++++++++++++++++ .../controller/specifications/packet.html | 303 +++++++++ documentation/controller/specifications/rule.html | 601 ++++++++++++++++++ documentation/fake.html | 72 +-- documentation/fake/specifications.html | 98 +++ documentation/firewall.html | 36 +- documentation/firewall/specifications.html | 95 +++ documentation/fss_basic_list_read.html | 36 +- .../fss_basic_list_read/specifications.html | 95 +++ documentation/fss_basic_list_write.html | 38 +- .../fss_basic_list_write/specifications.html | 95 +++ documentation/fss_basic_read.html | 36 +- documentation/fss_basic_read/specifications.html | 95 +++ documentation/fss_basic_write.html | 38 +- documentation/fss_basic_write/specifications.html | 95 +++ documentation/fss_embedded_list_read.html | 36 +- .../fss_embedded_list_read/specifications.html | 95 +++ documentation/fss_embedded_list_write.html | 38 +- .../fss_embedded_list_write/specifications.html | 95 +++ documentation/fss_extended_list_read.html | 36 +- .../fss_extended_list_read/specifications.html | 95 +++ documentation/fss_extended_list_write.html | 38 +- .../fss_extended_list_write/specifications.html | 95 +++ documentation/fss_extended_read.html | 36 +- .../fss_extended_read/specifications.html | 95 +++ documentation/fss_extended_write.html | 38 +- .../fss_extended_write/specifications.html | 95 +++ documentation/fss_identify.html | 38 +- documentation/fss_identify/specifications.html | 95 +++ documentation/fss_payload_read.html | 38 +- documentation/fss_payload_read/specifications.html | 95 +++ documentation/fss_payload_write.html | 38 +- .../fss_payload_write/specifications.html | 95 +++ documentation/fss_status_code.html | 30 +- documentation/fss_status_code/specifications.html | 95 +++ documentation/iki_read.html | 42 +- documentation/iki_read/specifications.html | 95 +++ documentation/iki_write.html | 30 +- documentation/iki_write/specifications.html | 95 +++ documentation/status_code.html | 30 +- documentation/status_code/specifications.html | 95 +++ documentation/utf8.html | 48 +- documentation/utf8/specifications.html | 95 +++ documents/standards/fll/fss-0000.txt | 28 +- documents/standards/fll/fss-0001.txt | 26 +- documents/standards/fll/fss-0002.txt | 30 +- documents/standards/fll/fss-0003.txt | 40 +- documents/standards/fll/fss-0004.txt | 8 +- documents/standards/fll/fss-0005.txt | 10 +- documents/standards/fll/fss-0006.txt | 8 +- documents/standards/fll/fss-0007.txt | 10 +- documents/standards/fll/fss-0008.txt | 2 +- documents/standards/fll/fss-0009.txt | 30 +- documents/standards/fll/fss-000a.txt | 28 +- documents/standards/fll/fss-000b.txt | 2 +- documents/standards/fll/fss-000c.txt | 8 +- documents/standards/fll/fss-000d.txt | 18 +- documents/standards/fll/fss-000e.txt | 55 +- documents/standards/fll/fss-000f.txt | 18 +- documents/standards/fll/fss.txt | 75 ++- documents/standards/fll/iki-0001.txt | 18 +- documents/standards/fll/iki-0002.txt | 8 +- documents/standards/fll/iki.txt | 46 +- fll/design.html | 2 +- fll/specifications.html | 49 +- fll/specifications/fss/fss-0000.html | 2 +- fll/specifications/fss/fss-0001.html | 2 +- fll/specifications/fss/fss-0002.html | 2 +- fll/specifications/fss/fss-0003.html | 2 +- fll/specifications/fss/fss-0004.html | 2 +- fll/specifications/fss/fss-0005.html | 2 +- fll/specifications/fss/fss-0006.html | 2 +- fll/specifications/fss/fss-0007.html | 2 +- fll/specifications/fss/fss-0008.html | 2 +- fll/specifications/fss/fss-0009.html | 2 +- fll/specifications/fss/fss-000a.html | 8 +- fll/specifications/fss/fss-000b.html | 2 +- fll/specifications/fss/fss-000c.html | 2 +- fll/specifications/fss/fss-000d.html | 2 +- fll/specifications/fss/fss-000e.html | 2 +- fll/specifications/fss/fss-000f.html | 2 +- fll/specifications/iki/iki-0000.html | 2 +- fll/specifications/iki/iki-0001.html | 2 +- fll/specifications/iki/iki-0002.html | 2 +- news/2022_05_01-website_redesign.html | 2 +- news/2022_05_06-basic_program_documentation.html | 2 +- news/2022_05_16-fll_specifications_added.html | 2 +- news/2022_06_04-librem_to_freedom.html | 2 +- news/2022_07_02-fll_0_5_10_release.html | 2 +- projects.html | 60 +- specification.html | 322 ++++++++++ 114 files changed, 6491 insertions(+), 870 deletions(-) create mode 100644 documentation/byte_dump/specifications.html create mode 100644 documentation/control/specifications.html create mode 100644 documentation/control/specifications/packet_request.html create mode 100644 documentation/control/specifications/packet_response.html create mode 100644 documentation/control/specifications/settings.html create mode 100644 documentation/controller/specifications.html create mode 100644 documentation/controller/specifications/action.html create mode 100644 documentation/controller/specifications/entry.html create mode 100644 documentation/controller/specifications/exit.html create mode 100644 documentation/controller/specifications/packet.html create mode 100644 documentation/controller/specifications/rule.html create mode 100644 documentation/fake/specifications.html create mode 100644 documentation/firewall/specifications.html create mode 100644 documentation/fss_basic_list_read/specifications.html create mode 100644 documentation/fss_basic_list_write/specifications.html create mode 100644 documentation/fss_basic_read/specifications.html create mode 100644 documentation/fss_basic_write/specifications.html create mode 100644 documentation/fss_embedded_list_read/specifications.html create mode 100644 documentation/fss_embedded_list_write/specifications.html create mode 100644 documentation/fss_extended_list_read/specifications.html create mode 100644 documentation/fss_extended_list_write/specifications.html create mode 100644 documentation/fss_extended_read/specifications.html create mode 100644 documentation/fss_extended_write/specifications.html create mode 100644 documentation/fss_identify/specifications.html create mode 100644 documentation/fss_payload_read/specifications.html create mode 100644 documentation/fss_payload_write/specifications.html create mode 100644 documentation/fss_status_code/specifications.html create mode 100644 documentation/iki_read/specifications.html create mode 100644 documentation/iki_write/specifications.html create mode 100644 documentation/status_code/specifications.html create mode 100644 documentation/utf8/specifications.html create mode 100644 specification.html diff --git a/css/kevux.css b/css/kevux.css index 2936300..6df8e06 100644 --- a/css/kevux.css +++ b/css/kevux.css @@ -81,6 +81,10 @@ display: block; font-weight: normal; +} + +.kevux > .content-block > .nav-block > .nav-menu > .nav-item.highlight, +.kevux > .content-block > .nav-block > .nav-menu > .nav-item.highlight > .nav-text.unlink { background-color: #e5f5c9; } @@ -104,6 +108,7 @@ .kevux > .content-block > .main-block .grid { column-gap: 1rem; + margin-bottom: 1rem; } .kevux > .content-block > .main-block .grid.wide { @@ -200,10 +205,12 @@ color: #724801; } +.kevux.specification > .content-block > .main-block .table.context-parameters > .set > .row:nth-child(even), .kevux.documentation > .content-block > .main-block .table.context-parameters > .set > .row:nth-child(even) { background-color: #efefef; } +.kevux.specification > .content-block > .main-block .table.context-parameters > .set > .row > .column:nth-child(1), .kevux.documentation > .content-block > .main-block .table.context-parameters > .set > .row > .column:nth-child(1) { text-align: center; } diff --git a/distributions/turtle/changelog.html b/distributions/turtle/changelog.html index cf7a698..fe49fc9 100644 --- a/distributions/turtle/changelog.html +++ b/distributions/turtle/changelog.html @@ -72,7 +72,7 @@
Documentation
Turtle Kevux -
+
Change Log
Turtle Kevux
diff --git a/distributions/turtle/documentation.html b/distributions/turtle/documentation.html index d699fcb..7c4b5d4 100644 --- a/distributions/turtle/documentation.html +++ b/distributions/turtle/documentation.html @@ -67,7 +67,7 @@
1.0.0 Release
-
+
Documentation
Turtle Kevux
diff --git a/distributions/turtle/documentation/additional.html b/distributions/turtle/documentation/additional.html index e603eb2..83c67ef 100644 --- a/distributions/turtle/documentation/additional.html +++ b/distributions/turtle/documentation/additional.html @@ -74,8 +74,8 @@
Server Configuration
-
-
Additional / Miscellaneous Notes
+
+
Additional Notes
Known Issues diff --git a/distributions/turtle/documentation/configuring.html b/distributions/turtle/documentation/configuring.html index 1dc066d..34b3fc6 100644 --- a/distributions/turtle/documentation/configuring.html +++ b/distributions/turtle/documentation/configuring.html @@ -67,7 +67,7 @@
Installing Turtle Kevux
-
+
System Configuration
diff --git a/distributions/turtle/documentation/credits.html b/distributions/turtle/documentation/credits.html index 58a1e8b..c296bb2 100644 --- a/distributions/turtle/documentation/credits.html +++ b/distributions/turtle/documentation/credits.html @@ -79,7 +79,7 @@
Known Issues
-
+
Credits
diff --git a/distributions/turtle/documentation/installing.html b/distributions/turtle/documentation/installing.html index f3001bd..6301b58 100644 --- a/distributions/turtle/documentation/installing.html +++ b/distributions/turtle/documentation/installing.html @@ -65,7 +65,7 @@
Booting and Running
-
+
Installing Turtle Kevux
diff --git a/distributions/turtle/documentation/problems.html b/distributions/turtle/documentation/problems.html index 64ffb97..e37bfbe 100644 --- a/distributions/turtle/documentation/problems.html +++ b/distributions/turtle/documentation/problems.html @@ -59,6 +59,9 @@
Turtle Kevux
+ Software Listing +
+
Booting and Running
@@ -73,7 +76,7 @@
Additional Notes
-
+
Known Issues
diff --git a/distributions/turtle/documentation/running.html b/distributions/turtle/documentation/running.html index b89f9e3..eb0b32f 100644 --- a/distributions/turtle/documentation/running.html +++ b/distributions/turtle/documentation/running.html @@ -61,7 +61,7 @@
Software Listing
-
+
Booting and Running
diff --git a/distributions/turtle/documentation/servers.html b/distributions/turtle/documentation/servers.html index 2b7a451..bd201ee 100644 --- a/distributions/turtle/documentation/servers.html +++ b/distributions/turtle/documentation/servers.html @@ -70,7 +70,7 @@
System Configuration
-
+
Server Configuration
diff --git a/distributions/turtle/documentation/software.html b/distributions/turtle/documentation/software.html index c883823..4e1c6ec 100644 --- a/distributions/turtle/documentation/software.html +++ b/distributions/turtle/documentation/software.html @@ -57,7 +57,7 @@
Documentation
Turtle Kevux
-
+
Software Listing
diff --git a/documentation.html b/documentation.html index 93a0e39..bbdea1d 100644 --- a/documentation.html +++ b/documentation.html @@ -122,12 +122,6 @@
UTF8
-
-
Specifications
-
-
-
APIs
-
… Collapse Menu @@ -187,10 +181,14 @@

- Projects like the Featureless Linux Library are focused entirely around provided standards for every aspect of the project. Numerous specifications are available describing these standards. At this time, the specifications have not been transcribed into a format for the web. They are stored in plain text within the source code repositories. + Projects like the Featureless Linux Library are focused entirely around provided standards for every aspect of the project. Numerous specifications are available describing these standards. At this time, the specifications have not been transcribed into a format for the web. They are stored in plain text within the source code repositories. +

+

+ There are two major groups of specifications, the Featureless Settings Specifications and the IKI Specifications. + Individual program projects may also have their own specifications. Each pogram has a specifications page that describes the specifications, if any, that are defined by that project.

- Many of these specifications may be found here: + Many of these specifications may also be found in the source code repositories:

  • https://sourceforge.net/p/fll/git/ci/development/tree/specifications/
    • diff --git a/documentation/byte_dump.html b/documentation/byte_dump.html index 9c22dbb..9ddd255 100644 --- a/documentation/byte_dump.html +++ b/documentation/byte_dump.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
    Back
    -
    +
    Documentation
    Byte Dump
    - About -
    -
    Standard Parameters
    @@ -67,6 +64,7 @@
    Specifications
    + Byte Dump
    APIs
    @@ -84,23 +82,17 @@

    Byte Dump Documentation

    -
    -
    -

    About

    -
    - -
    -

    - The byte_dump program is a tool for parsing and printing the bytes of all data within one or more files. -

    -

    - This tool operates similar to the classic hexdump program and provides similar functionality. However, the byte_dump program is not intended to be a complete replacemenet. Unlike the hexdump program, the byte_dump program is fully UTF-8 aware and even validates the Unicode sequences. -

    -

    - This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. -

    -
    -
    +
    +

    + The byte_dump program is a tool for parsing and printing the bytes of all data within one or more files. +

    +

    + This tool operates similar to the classic hexdump program and provides similar functionality. However, the byte_dump program is not intended to be a complete replacemenet. Unlike the hexdump program, the byte_dump program is fully UTF-8 aware and even validates the Unicode sequences. +

    +

    + This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. +

    +
    diff --git a/documentation/byte_dump/specifications.html b/documentation/byte_dump/specifications.html new file mode 100644 index 0000000..2167d7c --- /dev/null +++ b/documentation/byte_dump/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - Byte Dump - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + +
    +
    +
    +

    Byte Dump Specifications

    +
    + +
    +

    + The FLL project provides several specifications. + The Byte Dump does not use or provide any of these specifications. +

    +
    +
    +
    +
    + + diff --git a/documentation/control.html b/documentation/control.html index 60b2222..9139c46 100644 --- a/documentation/control.html +++ b/documentation/control.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
    Back
    -
    +
    Documentation
    Control
    - About -
    -
    Standard Parameters
    @@ -67,6 +64,16 @@
    Specifications
    + Control +
    +
    + Settings +
    +
    + Packet Request +
    +
    + Packet Response
    APIs
    @@ -84,20 +91,14 @@

    Control Documentation

    -
    -
    -

    About

    -
    - -
    -

    - The control program is a tool for sending commands to the controller program. -

    -

    - This tools is currently incomplete and is not guaranteed to work with the controller program. Further development will be made on this once the controller program is updated. The next development series is planned to focus on networking, which will include support for this. -

    -
    -
    +
    +

    + The control program is a tool for sending commands to the controller program. +

    +

    + This tools is currently incomplete and is not guaranteed to work with the controller program. Further development will be made on this once the controller program is updated. The next development series is planned to focus on networking, which will include support for this. +

    +
    diff --git a/documentation/control/specifications.html b/documentation/control/specifications.html new file mode 100644 index 0000000..f48f2a9 --- /dev/null +++ b/documentation/control/specifications.html @@ -0,0 +1,115 @@ + + + + Documentation - Control - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + +
    +
    +
    +

    Control Specifications

    +
    + +
    +

    + The FLL project provides several specifications. +

    +

    + The Control follows the following specifications: +

    + +

    + The Control defines the following specifications: +

    + +
    +
    +
    +
    + + diff --git a/documentation/control/specifications/packet_request.html b/documentation/control/specifications/packet_request.html new file mode 100644 index 0000000..cbc8d2b --- /dev/null +++ b/documentation/control/specifications/packet_request.html @@ -0,0 +1,158 @@ + + + + Documentation - Control - Specification - Packet Request + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + +
    +
    +
    +

    Control Packet Request Specification

    +
    + +
    +

    + The Control follows a Packet Request Specification. + This specification is incomplete at this time as the functionality is not yet written. + This specification is intended to be shared with the Controller program. +

    +
    + +
    +
    +

    Control Packet Request Documentation

    +
    + +
    +

    + The Control program sends packets and receives packet responses from the Controller program over the Controller program's control socket. + This documentation describes the request packets sent by this program. +

    +

    + The purpose of these request packets are to ask the Controller program to perform a requested action. +

    +

    + The communications to/from the Controller program utilize the FSS-000F (Simple Packet). + This Simple Packet is expected to contain within it the FSS-000E (Payload) format. +

    +

    + The Payload contains within it a Header and a Payload. + Note the potential confusion here between the Payload when referring to the Packet format and the Payload referring to the Content within the Payload Packet. + To avoid this, henceforth "Payload Packet" refers to the FSS-000E (Payload) used within the FSS-000F (Simple Packet). + The "Payload Header" refers to either the Object (header:) or Content within the Payload Packet representing the header. + The "Payload Object" refers to the Object within the Payload Packet (ie: payload:). + The "Payload Content" refers to the Content within the Payload Packet. +

    +

    + The FSS-000E (Payload) is very flexible in what it allows within the Header of the Payload Packet. + The Control program is more restrictive and supports only a subset of the possibilities (which this is explicitly allowed by the Specification). +

    +

    + The Control program only supports the following Payload Packet header Objects for the request: +

    +
      +
    • type: Allows only a single type header Object and may only be one of: controller, error, or init.
      • +
    • length: Allows only a single length header Object and must properly describe the length of the entire Payload Packet as per the referenced Specifications.
      • +
    • action: Allows only a single action header Object and whose first Content must only be one of: freeze, kexec, kill, pause, reboot, reload, rerun, restart, resume, shutdown, start, stop, and thaw.
      • +
    +

    + The number of Content associated with a action are specific to the requirements of that action. +

    +

    + The Payload Content is not used and should always be of length 0. +

    +

    + The Payload Content represents the rule being started in FSS-0001 (Extended) format, such as service sshd. +

    +

    + For example, given the command: control start service sshd in 5 minutes. + The action Object would be start service sshd in 5 minutes. +

    +
    +
    +
    +
    +
    + + diff --git a/documentation/control/specifications/packet_response.html b/documentation/control/specifications/packet_response.html new file mode 100644 index 0000000..2deba81 --- /dev/null +++ b/documentation/control/specifications/packet_response.html @@ -0,0 +1,203 @@ + + + + Documentation - Control - Specification - Packet Response + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + +
    +
    +
    +

    Control Packet Response Specification

    +
    + +
    +

    + The Control follows a Packet Response Specification. + This specification is incomplete at this time as the functionality is not yet written. + This specification is intended to be shared with the Controller program. +

    +
    + +
    +
    +

    Control Packet Response Documentation

    +
    + +
    +

    + The Control program sends packets and receives packet responses from the Controller program over the Controller program's control socket. + This documentation describes the expected response packets and how these response packets are handled. +

    +

    + The communications to/from the Controller program utilize the FSS-000F (Simple Packet). + This Simple Packet is expected to contain within it the FSS-000E (Payload) format. +

    +

    + The Payload contains within it a Header and a Payload. + Note the potential confusion here between the Payload when referring to the Packet format and the Payload referring to the Content within the Payload Packet. + The "Payload Header" refers to either the Object (header:) or Content within the Payload Packet representing the header. + The "Payload Object" refers to the Object within the Payload Packet (ie: payload:). + The "Payload Content" refers to the Content within the Payload Packet. +

    +

    + The FSS-000E (Payload) is very flexible in what it allows within the Header of the Payload Packet. + The Control program is more restrictive and supports only a subset of the possibilities (which this is explicitly allowed by the Specification). +

    +

    + The Control program only supports the following Payload Packet header Objects for the response: +

    +
      +
    • + status: Allows only a single status header Object. +
      • +
    • + type: Allows only a single type header Object and may only be one of: controller, error, or init. +
      • +
    • + action: Allows only a single action header Object and must only be one of: freeze, kexec, kill, pause, reboot, reload, rerun, restart, resume, shutdown, start, stop, and thaw. +
      • +
    • + length: Allows only a single length header Object and must properly describe the length of the entire Payload Packet as per the referenced Specifications. +
      • +
    +

    + The error type response Payload Packet is treated as an error response. + For any error responses that are associated with an action, then the action header is provided (otherwise it is not expected and is ignored). + For any error responses the Payload Content may be empty but when it is not, then the Payload Content is a single string representing a message further describing the error or the reason for the error. + These error responses represents errors in attempting to perform some action. + These responses are not used for actions that return an error as the result of a proper execution or performing of that action. +

    +

    + The controller type response Payload Packet represents a response regarding the result of performing a requested action. + There must always be an action designating the action this response is in regards to. +

    +

    + Only the following are (currently) supported as a status: +

    +
      +
    • + F_busy: When unable to perform the action as because the service is too busy or the +
      • +
    • + F_done: When successfully performed the action but the action does not return success or failure. +
      • +
    • + F_failure: When successfully performed the action and the action returned some sort of failure or error. +
      • +
    • + F_success: When successfully performed the action and the action returned some sort of success. +
      • +
    +

    + When using the -R/--return parameter, the program prints specially formatted messages to help make the output more scriptable. +

    +

    + The form response [type] [action] [status]. +

    +

    + Examples: +

    +
      +
    • + A response that designates the action failed might look like: response controller my_action F_failure. +
      • +
    • + A response that designates the controller ran out of memory, preventing the action from being run: response error my_action F_memory_not. +
      • +
    • + A response that designates the controller ran successfully: response controller my_action F_success. +
      • +
    +

    + When the Control program fails to function due to some error, there will be no specially formatted message printed. + When the Controller program fails before it can perform the requested action, then a response error [action] [status] formatted message is printed. + When the Controller program successfully performs the action but the result of that action is an error, then a response controller [action] F_failure formatted message is printed. +

    +
    +
    +
    +
    +
    + + diff --git a/documentation/control/specifications/settings.html b/documentation/control/specifications/settings.html new file mode 100644 index 0000000..6107ba6 --- /dev/null +++ b/documentation/control/specifications/settings.html @@ -0,0 +1,229 @@ + + + + Documentation - Control - Specification - Settings + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + +
    +
    +
    +

    Control Settings Specification

    +
    + +
    +

    + The Control defines the Settings Specification. + This specification describes how the settings file is used by the Control program. +

    +

    + The control settings "settings" file follows the FSS-0001 (Extended) format. +

    +

    + Each Object represents a settings property name. + There is only a distinct set of setting property names (see below). +

    +

    + Each Content represents the values associated with that property. + Additional restrictions are applied to each Content depending on each specific Object name (see below). +

    +

    + Object Names and their respective Content purpose/restrictions: +

    +
      +
    • name_socket: Must only be a single valid filename, without the directory.
      • +
    • path_socket: Must only be a single valid directory.
      • +
    • path_socket_prefix: Zero or one string representing a file name.
      • +
    • path_socket_suffix: Zero or one string representing a file name.
      • +
    +
    + +
    +
    +

    Control Settings Documentation

    +
    + +
    +

    + The settings file provides default or system-wide settings. + The system-wide settings file is loaded by default but a custom settings file may be alternatively specified. + Using this avoids the need to add additional paramters to the command line when calling the Control program. +

    +

    + When this file is not specified any hardcoded defaults compiled into the program are used. +

    +

    + The location of the settings file is compile time specific and should be changed depending on the particular design of the system. + The default path for the control settings file is something like /etc/control/settings. +

    +
      +
    • +
      + name_socket +
      +

      + This represents the file name used to construct the full socket path. + The file name represents the name of the file but any file extensions, such as .suffix, should likely use path_socket_suffix to specify the file extension. +

      +

      + When not defined the compiled in default is used. + The default socket path directory is generally default but this could be changed during compile time. +

      +

      + This is required to not be empty so when the Object path_socket is defined without any Content, then an error is expected to be thrown. +

      +

      + This is used along with the path_socket, path_socket_prefix, and the path_socket_suffix to construct the socket file. +

      +
      • +
    • +
      + path_socket +
      +

      + This represents the directory path to the socket file provided by the controller or init service. + This directory path is separate from the file name part so that the name can be more dynamically constructed without having to specify a full directory path each time. +

      +

      + When not defined the compiled in default is used. + The default socket path directory is generally /var/run/controller but this could be changed during compile time. +

      +

      + When the Object path_socket is defined without any Content, then no path is added (resulting in the socket relative to the callers current working directory). +

      +

      + This is used along with the path_socket_prefix, the path_socket_suffix, and the name_socket to construct the socket file. + A full socket path might look something like /var/run/controller/controller-default.socket. +

      +

      + It is common for the Controller program to be compiled as an init program. + In this case it may be common for the full socket path to instead be something more like /var/run/init/init-default.socket. +

      +
      • +
    • +
      + path_socket_prefix +
      +

      + This represents a prefix used to construct the full socket path. + This prefix is prepended to the socket file name. +

      +

      + When not defined the compiled in default is used. + The default path prefix is generally controller- but this could be changed during compile time. +

      +

      + When the Object path_socket_prefix is defined without any Content, then no prefix is prepended. +

      +

      + This is used along with the path_socket, the path_socket_suffix, and the name_socket to construct the socket file. +

      +
      • +
    • +
      + path_socket_suffix +
      +

      +

      + This represents a suffix used to construct the full socket path. + This suffix is appended to the socket file name. +

      +

      + When not defined the compiled in default is used. + The default path suffix is generally .socket but this could be changed during compile time. +

      +

      + When the Object path_socket_suffix is defined without any Content, then no suffix is appended. +

      +

      + This is used along with the path_socket, the path_socket_prefix, and the name_socket to construct the socket file. +

      +
      • +
    +
    +
    +
    +
    +
    + + diff --git a/documentation/controller.html b/documentation/controller.html index 1cdc40f..ce4ff6e 100644 --- a/documentation/controller.html +++ b/documentation/controller.html @@ -8,7 +8,7 @@ - + @@ -52,21 +52,40 @@
    Back
    -
    +
    Documentation
    Controller
    - About -
    -
    Standard Parameters
    Program Parameters
    + Simulate +
    +
    + Time +
    +
    Specifications
    + Controller +
    +
    + Action +
    +
    + Entry +
    +
    + Exit +
    +
    + Packet +
    +
    + Rule
    APIs
    @@ -84,38 +103,32 @@

    Controller Documentation

    -
    -
    -

    About

    -
    - -
    -

    - The controller program is a tool for controller other programs. -

    -

    - This tool is designed to configured to perform and execute any tasks given across multiple languages and it also has support for operating as an init program. There are special compile-time configurations needed to make this properly operate as an init program. -

    -

    - This tool operates similar to the fake program and can even be seen as an evolution to the fake program. The controller program, however is not a replacement to the fake program as it is more generalized. -

    -

    - This tool also provides additional features for making it easierr to test and write controller instructions. These features include partial simulation and validation modes. -

    -

    - In partial simulation mode, anything that the controller program has full control over and can simulate is simulated. Actual programs and scripts themselves, therefore, cannot be simulated. However, it may be possible to use an environment variables or similar and pass settings to the called program or script if the called program or script is simulation and testing aware. -

    -

    - The validation mode is for making this tool more scriptable. By providing validation, the controller instructions can be validated, in which case a success or failure result is returned and any problems or warnings may be printed to the caller of this tool. -

    -

    - This tool is not currently fully functional as an init program replacement because the networking aspects are not yet written or fully hashed out. The contol program is also another key part to the contoller program in getting this to work as an init program. Ideally, once this support is complete, it should be possible to replace init programs, such as SystemD, with the controller program. -

    -

    - Further development will be made on this once the controller program is updated. The next development series is planned to focus on networking, which will include support for this. -

    -
    -
    +
    +

    + The controller program is a tool for controller other programs. +

    +

    + This tool is designed to configured to perform and execute any tasks given across multiple languages and it also has support for operating as an init program. There are special compile-time configurations needed to make this properly operate as an init program. +

    +

    + This tool operates similar to the fake program and can even be seen as an evolution to the fake program. The controller program, however is not a replacement to the fake program as it is more generalized. +

    +

    + This tool also provides additional features for making it easierr to test and write controller instructions. These features include partial simulation and validation modes. +

    +

    + In partial simulation mode, anything that the controller program has full control over and can simulate is simulated. Actual programs and scripts themselves, therefore, cannot be simulated. However, it may be possible to use an environment variables or similar and pass settings to the called program or script if the called program or script is simulation and testing aware. +

    +

    + The validation mode is for making this tool more scriptable. By providing validation, the controller instructions can be validated, in which case a success or failure result is returned and any problems or warnings may be printed to the caller of this tool. +

    +

    + This tool is not currently fully functional as an init program replacement because the networking aspects are not yet written or fully hashed out. The contol program is also another key part to the contoller program in getting this to work as an init program. Ideally, once this support is complete, it should be possible to replace init programs, such as SystemD, with the controller program. +

    +

    + Further development will be made on this once the controller program is updated. The next development series is planned to focus on networking, which will include support for this. +

    +
    @@ -277,6 +290,119 @@

    + +
    +
    +

    Simulate Documentation

    +
    + +
    +

    + This describes the intent and purpose of the simulation and validation parameters. +

    +

    + The controller program is designed to support being run as an alternative to an init program (such as Sysvinit or SystemD). + To help prevent problems, simulation and validation functionality is provided. +

    +
      +
    • +

      + The validate functionality: +

      +

      + By itself will simply check the syntax of the Entry and Rule files (for Rule files specified in the Entry or Exit file). + Errors are reported and nothing is executed. + The controller program will return 0 on validation success and 1 on validation failure. +

      +
      • + +
    • +

      + The simulate functionality: +

      +

      + By itself will perform a simulated execution of all Rules designated by an Entry or Exit file. + The simulation is not a true simulation in that no program is ever called to perform any operations. + Furthermore, any script specified inside a Rule is only simulated as a whole and not its individual parts. + Once the Entry file is finished executing, the simulate will continue to run waiting on control commands. +

      +
      • + +
    • +

      + The simulate with validate functionality: +

      +

      + Will perform similar to validate functionality except that additional information of the Rules to be executed will be printed. + There will be neither execution nor simulated execution of any Rule when both simulate and validate are used together. +

      +
      • +

      + When a Rule is simulated, an empty script command (generally defaulting to bash) is executed in place of the actual program being executed for each program or script in the Rule file that is to be executed. + This allows for testing the designated permissions and other settings that would be applied when calling some program. + Control Groups are not simulated but are actually created and the simulating process will actually be placed within the Control Group. +

      +
    +
    + +
    +
    +

    Time Documentation

    +
    + +
    +

    + The controller program utilizes the unit of measurement called a Time, represented with uppercase T. + For comparison, a unit of Time is equivalent to a nanosecond, or 10^-9 seconds. + A MegaTime (MT) is therefore equivalent to a millisecond such that a millisecond is 10^-3 seconds. +

    +

    + A unit of Time is intended to represent some unit of Time such that a single 64-bit integer may hold all units of Time for a single calendar year. + This unit of Time does not and must not include Years (unlike Unixtime). + To convert from Time to Unixtime, one must have a year (which could be assumed to be the current year) and then calculate all of those calendar oddities. +

    +

    + A unit of Time by default is assumed to be in UTC. +

    +
      +
    • 1 (Earth) year ~= 31536000000000000 Time or 31536000 GT (GigaTime).
      • +
    • 1 (Earth) day = 86400000000000 Time or 86400 GT (GigaTime).
      • +
    • 1 (Earth) hour = 3600000000000 Time or 3600 GT (GigaTime).
      • +
    • 1 (Earth) minute = 60000000000 Time or 60 GT (GigaTime).
      • +
    • 1 (Earth) second = 1000000000 Time or 1 GT (GigaTime).
      • +
    +

    + Consequentially, 1 day in units of Time is easily represented as 86.4 TT (TeraTime). +

    +

    + The Time may be stored in its year string format. + In this format, a Year may be prepended to the Time followed by a single colon ':' to associate a year with the Time. + This Year has no minimum or maximum but may not have decimals. + For example, 2020:86400000000000 would represent: January 02, 2020 0:00 UTC. + For example, 2020:86.4 TT would represent: January 02, 2020 0:00 UTC. +

    +

    + A second unit of Time, called EpochTime, works the same way as Time except it represents seconds. + This unit is designated E. + The format is similar to Time, except there are two colons: 1970::1620874738 would represent: May 13, 2021 2:58:58 UTC. + When the year is not specified, then this is identical to UNIX Epoch. +

    +

    + A unit of EpochTime by default is assumed to be in UTC. +

    +
      +
    • 1 (Earth) year ~= 31536000 EpochTime or 31.536 GE (GigaEpochTime).
      • +
    • 1 (Earth) day = 86400 EpochTime
      • +
    • 1 (Earth) hour = 3600 EpochTime
      • +
    • 1 (Earth) minute = 60 EpochTime
      • +
    • 1 (Earth) second = 1 EpochTime
      • +
    • 1 GT (GigaTime) = 1 EpochTime
      • +
    +

    + Consequentially, 1 day in units of EpochTime is easily represented as 86.4 KE (KiloEpochTime). +

    +
    +
diff --git a/documentation/controller/specifications.html b/documentation/controller/specifications.html new file mode 100644 index 0000000..6627843 --- /dev/null +++ b/documentation/controller/specifications.html @@ -0,0 +1,132 @@ + + + + Documentation - Controller - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

Controller Specifications

+
+ +
+

+ The FLL project provides several specifications. +

+

+ The Controller follows the following specifications: +

+ +

+ The Controller defines the following specifications: +

+ +
+
+
+
+ + diff --git a/documentation/controller/specifications/action.html b/documentation/controller/specifications/action.html new file mode 100644 index 0000000..1f330a6 --- /dev/null +++ b/documentation/controller/specifications/action.html @@ -0,0 +1,222 @@ + + + + Documentation - Controller - Specification - Action + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

Controller Action Specification

+
+ +
+

+ The Entry, Exit, and Rule files each utilize an Action. +

+
+ +
+
+

Action Documentation

+
+ +
+

+ This describes the intent and purpose of the actions provided for individual Rules (or things related to a Rule). +

+

+ Each Action represents a specific intent and purpose but many of these actions are customizable via the rule file. + One should expect an Action to operate as described here but the system administrator or distributor is fully capable of doing something different. + For those doing something different, appropriate documentation is suggested. +

+

+ These actions should be usable by any control program that communicates with this controller program. + Should any control or controller program implementation not support any particular Action for any reason, one should report that the Action is unsupported. +

+

+ Freeze Action: +

+
    +
  • The Freeze Action is an extension of a Control Group.
    • +
  • This is internal to the controller program and is not customizable via any Rule file.
    • +
  • For a customizable freeze-like capability, look into the Pause and Resume Actions.
    • +
  • This is the complement of the Thaw Action.
    • +
  • This designates that a processes Control Group is to be frozen.
    • +
  • All Rules (or any process not controlled by the controller) that is within the same Control Group will be frozen.
    • +
  • (@todo consider instead designing this around the Control Groups instead of a rule.)
    • +
  • (This documentation will likely change with consideration to the above @todo once this gets implemented.)
    • +
  • This must not attempt to freeze (or unfreeze) the Control Group that the controller belongs to.
    • +
  • Therefore, if a Rule does not specify a Control Group, then it is likely that the Freeze Action will be unsupported for that Rule/Control Group.
    • +
+

+ Kill Action: +

+
    +
  • Forcefully terminate some process controlled by the controller.
    • +
  • This action cannot be blocked and it is recommended to use a Stop Action instead for a more proper termination.
    • +
+

+ Pause Action: +

+
    +
  • The Pause Action will pause (or freeze) the process controlled by the Rule.
    • +
  • Although similar to the Freeze Action, this is intended to communicate to an individual process and inform to Pause.
    • +
  • This is complemented by the Resume Action.
    • +
+

+ Restart Action: +

+
    +
  • The Restart Action will either perform a Stop Action and then a Restart Action or it will perform the Restart Action designated in some Rule file.
    • +
  • Ideally this should inform some process to perform its own restart routines.
    • +
+

+ Resume Action: +

+
    +
  • The Resume Action will unpause (or unfreeze) the process controlled by the Rule.
    • +
  • Although similar to the Thaw Action, this is intended to communicate to an individual process and inform to Resume.
    • +
  • This is complemented by the Pause Action.
    • +
+

+ Reload Action: +

+
    +
  • The Reload Action will perform the Reload Action designated in some Rule file.
    • +
  • Ideally this should inform some process to perform its own reload routines.
    • +
  • Many programs often differentiate the concept reload from the concept restart in that the program remains running during a reload.
    • +
+

+ Start Action: +

+
    +
  • The Start Action will perform the Start Action designated in some Rule file.
    • +
  • This action should be used to start some program or script.
    • +
  • This is the action called by Entry file.
    • +
  • This is complemented by the Stop Action.
    • +
+

+ Stop Action: +

+
    +
  • The Stop Action will perform the Stop Action designated in some Rule file.
    • +
  • This action should be used to stop some program or script.
    • +
  • This is the action called for all running controlled processes on shutdown.
    • +
  • This is complemented by the Start Action.
    • +
+

+ Thaw Action: +

+
    +
  • The Thaw Action is an extension of a Control Group.
    • +
  • This is internal to the controller program and is not customizable via any Rule file.
    • +
  • For a customizable thaw-like capability, look into the Pause and Resume Actions.
    • +
  • This is the complement of the Freeze Action.
    • +
  • This designates that a processes Control Group is to be unfrozen.
    • +
  • All Rules (or any process not controlled by the controller) that is within the same Control Group will be frozen.
    • +
  • (@todo consider instead designing this around the Control Groups instead of a rule.)
    • +
  • (This documentation will likely change with consideration to the above @todo once this gets implemented.)
    • +
  • This must not attempt to thaw (or unthaw) the Control Group that the controller belongs to.
    • +
  • Therefore, if a Rule does not specify a Control Group, then it is likely that the Thaw Action will be unsupported for that Rule/Control Group.
    • +
+
+
+
+
+
+ + diff --git a/documentation/controller/specifications/entry.html b/documentation/controller/specifications/entry.html new file mode 100644 index 0000000..0935646 --- /dev/null +++ b/documentation/controller/specifications/entry.html @@ -0,0 +1,704 @@ + + + + Documentation - Controller - Specification - Entry + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

Controller Entry Specification

+
+ +
+

+ The Entry files follow the FSS-0005 (Somewhat Basic List) format. +

+

+ An Entry file name is expected to have the file extension .entry. +

+

+ For each Entry file: +

+
    +
  • The outer most part is a FSS-0002 (Basic List).
    • +
  • The Basic List Object is considered the Item.
    • +
  • The Basic List Content are considered the Actions.
    • +
  • The Actions are FSS-0001 (Extended).
    • +
  • Each Action Object is the Action Name.
    • +
  • Each Action Content are the Action Parameters.
    • +
+

+ The Items: +

+
    +
  • main: required.
    • +
  • +
    settings: optional, Actions may be one of:
    +
      +
    • +
      control: One to two Content.
      +
        +
      • The first Content is a relative or absolute path to a socket file.
        • +
      • The second Content an optional "readonly".
        • +
      +
      • +
    • control_group: Exactly one Content that is a group name or group id.
      • +
    • control_mode: Exactly one Content that is a valid file mode.
      • +
    • control_user: Exactly one Content that is a user name or user id.
      • +
    • define: Two Content, the first Content must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits).
      • +
    • mode: Exactly one Content that is one of program or service.
      • +
    • parameter: Two Content, the first Content must be a case-sensitive valid IKI name and the second being an IKI value.
      • +
    • pid: Exactly one Content that is one of disable, require, or ready.
      • +
    • pid_file: Exactly one Content that is a relative or absolute path to a pid file.
      • +
    • session: Exactly one Content that is one of new or same.
      • +
    • show: Exactly one Content that is one of normal or init.
      • +
    • timeout: One or Two content with the first being one of exit, start, stop, or kill and the (optional) second Content being a positive whole number or 0.
      • +
    +
    • +
+

+ The Entry file may have any other valid Item Objects, but only the above are reserved. +

+

+ The Actions: +

+
    +
  • +
    consider: One or more Content.
    +
      +
    • The first Content is the relative file path (without any leading/trailing slashes and without file extension).
      • +
    • The second Content is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    execute: One or more Content.
    +
      +
    • The first Content is the program name or full path to the program (the program may be a script).
      • +
    • All remaining Content are passed as parameters to the program being executed.
      • +
    +
    • +
  • failsafe: One Content that is a valid Object name, except for the reserved main.
    • +
  • +
    freeze: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • item: One Content that is a valid Object name, except for the reserved main.
    • +
  • +
    kill: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    pause: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    ready: Zero or One Content.
    +
      +
    • +
      The first may only be one of:
      +
        +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    reload: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    restart: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    resume: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    start: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    stop: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    thaw: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    timeout: One or two Content.
    +
      +
    • +
      The first being one of:
      +
        +
      • exit
        • +
      • start
        • +
      • stop
        • +
      • kill
        • +
      +
      • +
    +
    • +
  • The (optional) second Content being a positive whole number or 0.
    • +
+
+ +
+
+

Entry Documentation

+
+ +
+

+ This describes the intent and purpose of an Entry file. +

+

+ An Entry file, such as default.entry, is intended to store a set of rules in which the controller will process on execution. + These are used to run some set of commands, such as booting a system. +

+

+ The main Item Object is always executed first (Therefore main is both reserved and required). + All other Basic List Objects are not executed unless either an item or a failsafe specifies a valid Item name. + Execution of all Items is top-down. +

+

+ The settings item Object: +

+
    +
  • Represents Entry settings and is not an item that can be executed.
    • +
  • A number of settings are supported, but if this Item Object is not specified, then defaults are used.
    • +
  • +
    + The following settings are available: control, control_group, control_mode, control_user, define, mode, parameter, pid, pid_file, session, show. +
    +

    + The control setting: +

    +
      +
    • Represents the path to the socket file in which the Controller uses to communicate over with clients such as a Control program.
      • +
    • A relative path is relative to the Controller PID directory.
      • +
    • An absolute path is treated exactly as the path given.
      • +
    • If no socket setting is specified, then no socket will be made available.
      • +
    • This socket file is only created once ready mode is achieved.
      • +
    • Providing readonly after the socket path instructs the Controller program not to create or delete the Socket file because the file system is assumed to be readonly.
      • +
    • The socket file itself must therefore already exist.
      • +
    • This should be possible in the cases of file systems that have pre-created a socket file at the designated path.
      • +
    • When readonly, the group, mode, and user are also not processed effectively resulting in the control_group, control_mode, and control_user settings being ignored.
      • +
    • Future versions might expand this into supporting network addresses in addition to socket files.
      • +
    +

    + The control_group setting: +

    +
      +
    • Represents the group name or group ID to assign to the socket file as the group.
      • +
    +

    + The control_mode setting: +

    +
      +
    • Represents the file mode assigned to the socket file.
      • +
    • This could either be the string version that might look like u+rw-x,g+r-wx,o-rwx or a numeric value like 0750.
      • +
    +

    + The define setting: +

    +
      +
    • Use this to define an environment variable (this overwrites any existing environment variable with this name).
      • +
    • A define is both exported as an environment variable as well as exposed as an IKI variable.
      • +
    • Example IKI variable substitution: for define PATH /bin:/sbin, the associated IKI variable would look like: define:"PATH".
      • +
    • All environment variables, including those defined using this, must be in the environment list in any given Rule to be exported to the executed process.
      • +
    • Environment variables added here that are not added to the environment are still exposed as an IKI variable.
      • +
    • This is only expanded within any Rule operated on by this Entry.
      • +
    +

    + The mode setting: +

    +
      +
    • Represents the mode in which the Entry is operating in.
      • +
    • +
      The following modes are supported: program and service.
      +

      + The program mode: +

      +
        +
      • Designates that the Entry operates as a program and exits when complete.
        • +
      • Will call the exit with the same name as this Entry, but with the extension exit, such as default.exit.
        • +
      • Supports the Item Action execute to execute a program (switching the controller program entirely with the executed process).
        • +
      +

      + The service mode: +

      +
        +
      • Designates that the Entry operates as a service and will sit and wait for control commands when complete.
        • +
      • Will call the exit with the same name as this Entry, but with the extension exit, such as default.exit.
        • +
      • Does not support the Item Action execute.
        • +
      • This is the default mode.
        • +
      +
      • +
    +

    + The parameter setting: +

    +
      +
    • Use this to define an IKI variable name and value.
      • +
    • These do not conflict with environment variables and are not exposed as environment variables.
      • +
    • Example IKI variable substitution: for parameter hello world, the associated IKI variable would look like: parameter:"hello".
      • +
    • This is only expanded within any Rule operated on by this Entry.
      • +
    +

    + The pid setting: +

    +
      +
    • Represents how the Entry PID file is generated or not.
      • +
    • The following modes are supported: disable, require, and ready.
      • +
    • For disable, not PID file representing the Entry is created.
      • +
    • For require, check to see if the PID file exists for an Entry at startup and then when ready create a PID file, display error on PID file already exists or on failure and then fail.
      • +
    • For ready, when ready create a PID file, display error on failure and then fail (does not check if PID file exists).
      • +
    +

    + The pid_file setting: +

    +
      +
    • When pid is not disabled this represents the path to the PID file.
      • +
    • If -p or --pid is passed to the controller program, then this value is ignored in favor of the value passed along the command line.
      • +
    +

    + The session setting: +

    +
      +
    • Represents the default way in which child processes are executed.
      • +
    • This default can be overridden by individual Rules.
      • +
    • For new, Execute Rule processes in a new session setting the process group to the executed process' id (making the executed process a controlling terminal).
      • +
    • For same, Execute Rule processes in the same session where the process group is set to the parent process id.
      • +
    +

    + The show setting: +

    +
      +
    • Represents the way Entry processing presents information to the screen.
      • +
    • This applies only to the Entry and Rule processing itself and does not handle the output of programs and scripts being executed by some Entry or Rule.
      • +
    • The following show options are supported: normal and init.
      • +
    • For normal, will not report the start or stop of some Entry or Rule execution but will report any errors or warnings as appropriate.
      • +
    • For init, will report when starting programs and may include reporting success and failure status.
      • +
    +

    + The timeout setting: +

    +
      +
    • Represents the default timeouts for the Entry.
      • +
    • See the timeout Action below for details.
      • +
    +
    • +
+

+ The main item Object: +

+
    +
  • Each item supports the following Action Names: consider, execute, failsafe, freeze, item, kill, pause, reload, restart, ready, resume, start, stop, and timeout.
    • +
  • Of those types, the following are considered a rule Action: freeze, kill, pause, reload, restart, resume, start, stop, and thaw.
    • +
  • +

    + The consider Item Action: +

    +
      +
    • A special case of a rule Action.
      • +
    • All Action Parameters are the same as with the rule Action Parameters.
      • +
    • The difference is that consider is only processed (instead of being processed and executed) and when some rule Action designates that this consideration is required (via need), wanted (via want), or wished for (via wish) from the within the Rule file.
      • +
    • If this is determined to be executed, then this is immediately executed when needed, wanted or wished for and applies all properties as appropriate (such as asynchronous, for example).
      • +
    • If this is determined not to be executed, then this consider is ignored as if it was never there in the first place.
      • +
    +

    + The execute Item Action: +

    +
      +
    • Execute into the specified program.
      • +
    • On successful execution, the controller program will no longer be running and will be replaced with the designated program.
      • +
    • This Item Action is only supported when operating in program mode.
      • +
    +

    + The failsafe Item Action: +

    +
      +
    • Accepts only a valid Item Name in which will be executed when a failure is detected.
      • +
    • Only a single failsafe Item Action may function at a time.
      • +
    • Each successive failsafe Item Action specified replaces the previously defined failsafe Item Action (in a top-down manner).
      • +
    • When operating in failsafe, the require Item Action is ignored (given that it is meaningless once operating in failsafe mode).
      • +
    +

    + The failsafe Item Action: +

    +
      +
    • Accepts only a valid Item Name in which will be executed when a failure is detected.
      • +
    • Only a single failsafe Item Action may function at a time.
      • +
    • Each successive failsafe Item Action specified replaces the previously defined failsafe Item Action (in a top-down manner).
      • +
    • When operating in failsafe, the require Item Action is ignored (given that it is meaningless once operating in failsafe mode).
      • +
    +

    + The freeze Item Action: +

    +
      +
    • A rule Action for freezing some Control Group.
      • +
    • This Item Action will process the freeze inner Content of the named Rule.
      • +
    • This is specific to Control Groups and is not yet fully implemented.
      • +
    • Once implemented this documentation will need to be updated and clarified.
      • +

      + The item Item Action: +

      +
        +
      • Accepts only a valid Item Name in which will be immediately executed.
        • +
      • Any valid Item Name, except for the reserved main, may be used.
        • +
      +

      + The kill Item Action: +

      +
        +
      • A rule Action for forcibly terminating some process.
        • +
      • This Item Action will process the kill inner Content of the named Rule.
        • +
      +

      + The pause Item Action: +

      +
        +
      • A rule Action for pausing some process.
        • +
      • This Item Action will process the pause inner Content of the named Rule.
        • +
      +

      + The reload Item Action: +

      +
        +
      • A rule Action for pausing some process.
        • +
      • This Item Action will process the reload inner Content of the named Rule.
        • +
      +

      + The restart Item Action: +

      +
        +
      • A rule Action for pausing some process.
        • +
      • This Item Action will process the restart inner Content of the named Rule.
        • +
      +

      + The resume Item Action: +

      +
        +
      • A rule Action for pausing some process.
        • +
      • This Item Action will process the resume inner Content of the named Rule.
        • +
      +

      + The ready Item Action: +

      +
        +
      • Instructs the controller program when it is safe to perform normal tasks, such as creating the PID file.
        • +
      • When not specified, the state is always assumed to be ready.
        • +
      • For example, the controller program may be used as a full blown init replacement and therefore may need to mount the /var/run/ directory.
        • +
      • If the PID file is created at program start, then the /var/run/controller.pid would be written before the /var/run/ directory is ready.
        • +
      • This could be a problem, such as on a read-only file system the PID creation fails and controller bails out on error.
        • +
      • Adding ready essentially specifies a point in time in the Entry in which things are expected to be safe for such basic operations.
        • +
      • When the optional wait is provided, then ready will wait for all currently started asynchronous processes to complete before operating.
        • +
      +

      + The start Item Action: +

      +
        +
      • A rule Action for pausing some process.
        • +
      • This Item Action will process the start inner Content of the named Rule.
        • +
      +

      + The stop Item Action: +

      +
        +
      • A rule Action for pausing some process.
        • +
      • This Item Action will process the stop inner Content of the named Rule.
        • +
      +

      + The thaw Item Action: +

      +
        +
      • A rule Action for unfreezing some Control Group.
        • +
      • This Item Action will process the thaw inner Content of the named Rule.
        • +
      • This is specific to Control Groups and is not yet fully implemented.
        • +
      • Once implemented this documentation will need to be updated and clarified.
        • +
      +

      + The timeout Item Action: +

      +
        +
      • (This is not currently fully implemented, only exit is implemented.)
        • +
      • Provides default global settings for each of the four special situations: exit, kill, start, and stop.
        • +
      • Each of these may only have a single one exist at a time (one exit, one kill, one start, and one stop).
        • +
      • Each successive timeout Item Action, specific to each Action Name (such as start), specified replaces the previously defined timeout Action (in a top-down manner).
        • +
      • The second Content for each of these, when specified, may be a 0 or greater whole number representing the number of MegaTime (MT) (equivalent to milliseconds).
        • +
      • For kill, this represents the number of MegaTime to wait after stopping some Rule and that Rule has not yet stopped to forcefully stop the Rule (aka kill the Rule).
        • +
      • For start, this represents the number of MegaTime to wait after starting some Rule before assuming something went wrong and the Rule is returned as failed.
        • +
      • For stop, this represents the number of MegaTime to wait after stopping some Rule before assuming something went wrong and the Rule is returned as failed.
        • +
      • If the second Content is not specified, then this disables the type (prevents the specified timeout action).
        • +
      • For exit, this represents the number of MegaTime to wait when the Controller program is exiting (such as having received a terminate signal).
        • +
      • In this case, a terminate signal is sent to all child processes.
        • +
      • The exit timeout represents the amount of time to wait after sending the terminate signal before sending a kill signal to each child process still running.
        • +
      • When disabled, the program will not send a kill signal will continue running until all child processes to terminate.
        • +
      • The exit timeout does not get applied to any Rule.
        • +
      + +
    +
+
+ +
+
+

Entry Rule Documentation

+
+ +
+

+ There are multiple Entry Actions that are considered rule Actions. + These are: freeze, kill, pause, reload, restart, resume, start, stop, and thaw. +

+

+ The rule Actions immediately execute a named Rule file. +

+
    +
  • +

    + The first Action Parameter represents the Rule directory, which is a relative directory path the Rule file is to be found. +

    +
      +
    • Do not include leading or trailing slashes.
      • +
    • This is relative to the settings rules directory.
      • +
    +
    • +
  • +

    + The second Action Parameter represents the base name for the Rule file, without the file extension. +

    +
      +
    • This must not have any directory paths.
      • +
    +
    • +
  • +

    + The remaining Action Parameters may be specified in any order\: +

    +
      +
    • asynchronous: Designates that execution will not block (wait).
      • +
    • require: Designates that this Rule must succeed or trigger execution of failsafe.
      • +
    • wait: Designates that this Rule will not execute until all other Actions before this (including asynchronous ones) finish executing (in a top-down manner).
      • +
    +
    • +
+

+ The full path to the rule is relative to the settings, such that if the controller Rule settings are found in /etc/controller/rules/, then for a directory called [directory] and a Rule base name of [base_name], the resulting path would be: /etc/controller/rules/[directory]/[base_name].rule. +

+

+ It is important to note that for any given rule, execution within that rule may be internally asynchronous (even if the rule is synchronous). + For example, a service that is often called a daemon will execute in the background. + Until that execution succeeds and the daemon goes into the background the representing Rule will block. + After the daemon goes into the background, then the representing Rule will no longer block and be fully executed. +

+
+
+
+
+
+ + diff --git a/documentation/controller/specifications/exit.html b/documentation/controller/specifications/exit.html new file mode 100644 index 0000000..1ae5fee --- /dev/null +++ b/documentation/controller/specifications/exit.html @@ -0,0 +1,648 @@ + + + + Documentation - Controller - Specification - Exit + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

Controller Exit Specifications

+
+ +
+

+ The Exit files follow the FSS-0005 (Somewhat Basic List) format. +

+

+ An Exit file name is expected to have the file extension .exit. +

+

+ For each Exit file: +

+
    +
  • The outer most part is a FSS-0002 (Basic List).
    • +
  • The Basic List Object is considered the Item.
    • +
  • The Basic List Content are considered the Actions.
    • +
  • The Actions are FSS-0001 (Extended).
    • +
  • Each Action Object is the Action Name.
    • +
  • Each Action Content are the Action Parameters.
    • +
+

+ The Items: +

+
    +
  • main: required.
    • +
  • + settings: optional, Actions may be one of: +
      +
    • +
      control: One to two Content.
      +
        +
      • The first Content is a relative or absolute path to a socket file.
        • +
      • The second Content an optional readonly.
        • +
      +
      • +
    • pid: Exactly one Content that is one of disable, require, or ready.
      • +
    • session: Exactly one Content that is one of new or same.
      • +
    • show: Exactly one Content that is one of normal or init.
      • +
    • timeout: One or Two content with the first being one of exit, start, stop, or kill and the (optional) second Content being a positive whole number or 0.
      • +
    +
    • +
+

+ The Exit file may have any other valid Item Objects, but only the above are reserved. +

+

+ The Actions: +

+
    +
  • +
    consider: One or more Content.
    +
      +
    • The first Content is the relative file path (without any leading/trailing slashes and without file extension).
      • +
    • The second Content is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    failsafe: One Content that is a valid Object name, except for the reserved main.
    +
    • +
  • +
    freeze: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    item: One Content that is a valid Object name, except for the reserved main.
    +
    • +
  • +
    kill: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    pause: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    ready: Zero or One Content.
    +
      +
    • +
      The first may only be one of:
      +
        +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    reload: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    restart: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    resume: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    start: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    stop: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    thaw: Two or more Content.
    +
      +
    • The first Content that is the relative directory path (without any leading/trailing slashes).
      • +
    • The second Content that is the basename for a rule file.
      • +
    • +
      The third and beyond may only be one of:
      +
        +
      • asynchronous
        • +
      • require
        • +
      • wait
        • +
      +
      • +
    +
    • +
  • +
    timeout: One or two Content.
    +
      +
    • +
      The first being one of:
      +
        +
      • exit
        • +
      • start
        • +
      • stop
        • +
      • kill
        • +
      +
      • +
    +
    • +
  • The (optional) second Content being a positive whole number or 0.
    • +
+
+ +
+
+

Exit Documentation

+
+ +
+

+ This describes the intent and purpose of an Exit file. +

+

+ An Exit file, such as default.exit, is intended to store a set of rules in which the controller will process on execution. + These are used to run some set of commands, such as shutting down a system. +

+

+ An Exit is a special variation or subset of an Entry. +

+

+ The settings item Object: +

+
    +
  • Represents Exit settings and is not an item that can be executed.
    • +
  • A number of settings are supported, but if this Item Object is not specified, then defaults are used.
    • +
  • +
    + The following settings are available: pid and show. +
    +

    + The define setting: +

    +
      +
    • Use this to define an environment variable (this overwrites any existing environment variable with this name).
      • +
    • A define is both exported as an environment variable as well as exposed as an IKI variable.
      • +
    • Example IKI variable substitution: for define PATH /bin:/sbin, the associated IKI variable would look like: define:"PATH".
      • +
    • All environment variables, including those defined using this, must be in the environment list in any given Rule to be exported to the executed process.
      • +
    • Environment variables added here that are not added to the environment are still exposed as an IKI variable.
      • +
    • This is only expanded within any Rule operated on by this Exit.
      • +
    +

    + The mode setting: +

    +
      +
    • Represents the mode in which the Exit is operating in.
      • +
    • +
      The following modes are supported: program and service.
      +

      + The program mode: +

      +
        +
      • Designates that the Exit operates as a program and exits when complete.
        • +
      • Will call the exit with the same name as this Exit, but with the extension exit, such as default.exit.
        • +
      • Supports the Item Action execute to execute a program (switching the controller program entirely with the executed process).
        • +
      +

      + The service mode: +

      +
        +
      • Designates that the Exit operates as a service and will sit and wait for control commands when complete.
        • +
      • Will call the exit with the same name as this Exit, but with the extension exit, such as default.exit.
        • +
      • Does not support the Item Action execute.
        • +
      • This is the default mode.
        • +
      +
      • +
    +

    + The parameter setting: +

    +
      +
    • Use this to define an IKI variable name and value.
      • +
    • These do not conflict with environment variables and are not exposed as environment variables.
      • +
    • Example IKI variable substitution: for parameter hello world, the associated IKI variable would look like: parameter:"hello".
      • +
    • This is only expanded within any Rule operated on by this Exit.
      • +
    +

    + The pid setting: +

    +
      +
    • Represents how the Exit PID file is generated or not.
      • +
    • The following modes are supported: disable, require, and ready.
      • +
    • For disable, not PID file representing the Exit is created.
      • +
    • For require, check to see if the PID file exists for an Exit at startup and then when ready create a PID file, display error on PID file already exists or on failure and then fail.
      • +
    • For ready, when ready create a PID file, display error on failure and then fail (does not check if PID file exists).
      • +
    +

    + The show setting: +

    +
      +
    • Represents the way Exit processing presents information to the screen.
      • +
    • This applies only to the Exit and Rule processing itself and does not handle the output of programs and scripts being executed by some Exit or Rule.
      • +
    • The following show options are supported: normal and init.
      • +
    • For normal, will not report the start or stop of some Exit or Rule execution but will report any errors or warnings as appropriate.
      • +
    • For init, will report when starting programs and may include reporting success and failure status.
      • +
    +

    + The timeout setting: +

    +
      +
    • Represents the default timeouts for the Exit.
      • +
    • See the timeout Action below for details.
      • +
    +
    • +
+

+ The main item Object: +

+
    +
  • Each item supports the following Action Names: consider, execute, failsafe, freeze, item, kill, pause, reload, restart, ready, resume, start, stop, and timeout.
    • +
  • Of those types, the following are considered a rule Action: freeze, kill, pause, reload, restart, resume, start, stop, and thaw.
    • +
  • +

    + The consider Item Action: +

    +
      +
    • A special case of a rule Action.
      • +
    • All Action Parameters are the same as with the rule Action Parameters.
      • +
    • The difference is that consider is only processed (instead of being processed and executed) and when some rule Action designates that this consideration is required (via need), wanted (via want), or wished for (via wish) from the within the Rule file.
      • +
    • If this is determined to be executed, then this is immediately executed when needed, wanted or wished for and applies all properties as appropriate (such as asynchronous, for example).
      • +
    • If this is determined not to be executed, then this consider is ignored as if it was never there in the first place.
      • +
    +

    + The execute Item Action: +

    +
      +
    • Execute into the specified program.
      • +
    • On successful execution, the controller program will no longer be running and will be replaced with the designated program.
      • +
    • This Item Action is only supported when operating in program mode.
      • +
    +

    + The failsafe Item Action: +

    +
      +
    • Accepts only a valid Item Name in which will be executed when a failure is detected.
      • +
    • Only a single failsafe Item Action may function at a time.
      • +
    • Each successive failsafe Item Action specified replaces the previously defined failsafe Item Action (in a top-down manner).
      • +
    • When operating in failsafe, the require Item Action is ignored (given that it is meaningless once operating in failsafe mode).
      • +
    +

    + The failsafe Item Action: +

    +
      +
    • Accepts only a valid Item Name in which will be executed when a failure is detected.
      • +
    • Only a single failsafe Item Action may function at a time.
      • +
    • Each successive failsafe Item Action specified replaces the previously defined failsafe Item Action (in a top-down manner).
      • +
    • When operating in failsafe, the require Item Action is ignored (given that it is meaningless once operating in failsafe mode).
      • +
    +

    + The freeze Item Action: +

    +
      +
    • A rule Action for freezing some Control Group.
      • +
    • This Item Action will process the freeze inner Content of the named Rule.
      • +
    • This is specific to Control Groups and is not yet fully implemented.
      • +
    • Once implemented this documentation will need to be updated and clarified.
      • +

      + The item Item Action: +

      +
        +
      • Accepts only a valid Item Name in which will be immediately executed.
        • +
      • Any valid Item Name, except for the reserved main, may be used.
        • +
      +

      + The kill Item Action: +

      +
        +
      • A rule Action for forcibly terminating some process.
        • +
      • This Item Action will process the kill inner Content of the named Rule.
        • +
      +

      + The pause Item Action: +

      +
        +
      • A rule Action for pausing some process.
        • +
      • This Item Action will process the pause inner Content of the named Rule.
        • +
      +

      + The reload Item Action: +

      +
        +
      • A rule Action for pausing some process.
        • +
      • This Item Action will process the reload inner Content of the named Rule.
        • +
      +

      + The restart Item Action: +

      +
        +
      • A rule Action for pausing some process.
        • +
      • This Item Action will process the restart inner Content of the named Rule.
        • +
      +

      + The resume Item Action: +

      +
        +
      • A rule Action for pausing some process.
        • +
      • This Item Action will process the resume inner Content of the named Rule.
        • +
      +

      + The ready Item Action: +

      +
        +
      • Instructs the controller program when it is safe to perform normal tasks, such as creating the PID file.
        • +
      • When not specified, the state is always assumed to be ready.
        • +
      • For example, the controller program may be used as a full blown init replacement and therefore may need to mount the /var/run/ directory.
        • +
      • If the PID file is created at program start, then the /var/run/controller.pid would be written before the /var/run/ directory is ready.
        • +
      • This could be a problem, such as on a read-only file system the PID creation fails and controller bails out on error.
        • +
      • Adding ready essentially specifies a point in time in the Exit in which things are expected to be safe for such basic operations.
        • +
      • When the optional wait is provided, then ready will wait for all currently started asynchronous processes to complete before operating.
        • +
      +

      + The start Item Action: +

      +
        +
      • A rule Action for pausing some process.
        • +
      • This Item Action will process the start inner Content of the named Rule.
        • +
      +

      + The stop Item Action: +

      +
        +
      • A rule Action for pausing some process.
        • +
      • This Item Action will process the stop inner Content of the named Rule.
        • +
      +

      + The thaw Item Action: +

      +
        +
      • A rule Action for unfreezing some Control Group.
        • +
      • This Item Action will process the thaw inner Content of the named Rule.
        • +
      • This is specific to Control Groups and is not yet fully implemented.
        • +
      • Once implemented this documentation will need to be updated and clarified.
        • +
      +

      + The timeout Item Action: +

      +
        +
      • (This is not currently fully implemented, only exit is implemented.)
        • +
      • Provides default global settings for each of the four special situations: exit, kill, start, and stop.
        • +
      • Each of these may only have a single one exist at a time (one exit, one kill, one start, and one stop).
        • +
      • Each successive timeout Item Action, specific to each Action Name (such as start), specified replaces the previously defined timeout Action (in a top-down manner).
        • +
      • The second Content for each of these, when specified, may be a 0 or greater whole number representing the number of MegaTime (MT) (equivalent to milliseconds).
        • +
      • For kill, this represents the number of MegaTime to wait after stopping some Rule and that Rule has not yet stopped to forcefully stop the Rule (aka kill the Rule).
        • +
      • For start, this represents the number of MegaTime to wait after starting some Rule before assuming something went wrong and the Rule is returned as failed.
        • +
      • For stop, this represents the number of MegaTime to wait after stopping some Rule before assuming something went wrong and the Rule is returned as failed.
        • +
      • If the second Content is not specified, then this disables the type (prevents the specified timeout action).
        • +
      • For exit, this represents the number of MegaTime to wait when the Controller program is exiting (such as having received a terminate signal).
        • +
      • In this case, a terminate signal is sent to all child processes.
        • +
      • The exit timeout represents the amount of time to wait after sending the terminate signal before sending a kill signal to each child process still running.
        • +
      • When disabled, the program will not send a kill signal will continue running until all child processes to terminate.
        • +
      • The exit timeout does not get applied to any Rule.
        • +
      + +
    +
+
+ +
+
+

Exit Rule Documentation

+
+ +
+

+ There are multiple Exit Actions that are considered rule Actions. + These are: freeze, kill, pause, reload, restart, resume, start, stop, and thaw. +

+

+ The rule Actions immediately execute a named Rule file. +

+
    +
  • +

    + The first Action Parameter represents the Rule directory, which is a relative directory path the Rule file is to be found. +

    +
      +
    • Do not include leading or trailing slashes.
      • +
    • This is relative to the settings rules directory.
      • +
    +
    • +
  • +

    + The second Action Parameter represents the base name for the Rule file, without the file extension. +

    +
      +
    • This must not have any directory paths.
      • +
    +
    • +
  • +

    + The remaining Action Parameters may be specified in any order\: +

    +
      +
    • asynchronous: Designates that execution will not block (wait).
      • +
    • require: Designates that this Rule must succeed or trigger execution of failsafe.
      • +
    • wait: Designates that this Rule will not execute until all other Actions before this (including asynchronous ones) finish executing (in a top-down manner).
      • +
    +
    • +
+

+ The full path to the rule is relative to the settings, such that if the controller Rule settings are found in /etc/controller/rules/, then for a directory called [directory] and a Rule base name of [base_name], the resulting path would be: /etc/controller/rules/[directory]/[base_name].rule. +

+

+ It is important to note that for any given rule, execution within that rule may be internally asynchronous (even if the rule is synchronous). + For example, a service that is often called a daemon will execute in the background. + Until that execution succeeds and the daemon goes into the background the representing Rule will block. + After the daemon goes into the background, then the representing Rule will no longer block and be fully executed. +

+
+
+
+
+
+ + diff --git a/documentation/controller/specifications/packet.html b/documentation/controller/specifications/packet.html new file mode 100644 index 0000000..65b9474 --- /dev/null +++ b/documentation/controller/specifications/packet.html @@ -0,0 +1,303 @@ + + + + Documentation - Controller - Specification - Packet + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

Controller Packet Specifications

+
+ +
+

+ The controller program communicates use the FSS-000F (Packet). +

+

+ This specification declares how the Payload Block, which is in FSS-000E (Payload) format, is required to be used. +

+

+ Only a single header is allowed. +

+

+ Only a single payload is allowed. +

+

+ Packet Structure: +

+
    +
  • +

    + Packet is grouped into the following blocks: +

    +
      +
    • control: A single 1-byte block representing control codes.
      • +
    • size: A single 4-byte block representing the size of the entire packet, including the control block.
      • +
    +
    • +
+

+ The header Object contains the following FSS-0001 (Extended Object) (depending on type): +

+
    +
  • action: A valid action type: freeze, kexec, kill, pause, reboot, reload, rerun, restart, resume, shutdown, start, stop, or thaw.
    • +
  • length: A positive whole number inclusively between 0 and 4294965248 representing the length of the payload (may be in binary, octal, decimal, duodecimal, or hexidecimal).
    • +
  • status: The status code name or number representing an FSS status code, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal).
    • +
  • type: The packet type that is one of controller, error, or init.
    • +
+

+ When there are multiple Objects of the same name inside the header: +

+
    +
  • action: The order represents the order in which the actions are performed..
    • +
  • length: There may only be one length Object, all others after the first are ignored (may be in binary, octal, decimal, duodecimal, or hexidecimal).
    • +
  • status: A status for each action, in the same order as the order of the action, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal).
    • +
  • type: The first represent the type and all others represents a sub-type.
    • +
+

+ There are different headers and payload properties based on the type. +

+

+ The controller type: +

+
    +
  • Supports the following headers: action, length, status, and type.
    • +
  • Only a single action may be provided and must exist for request and response packets.
    • +
  • Only a single status may be provided and must exist for response packets.
    • +
  • The payload is dependent on the action.
    • +
+

+ The error type: +

+
    +
  • Supports the following headers: length, status, and type.
    • +
  • Only a single status may be provided and must exist for request and response packets.
    • +
  • The payload is a NULL terminated string whose length is defined by the length header Content.
    • +
+

+ There are different headers and payload properties based on the type. +

+

+ The init type: +

+
    +
  • Supports the following headers: action, length, status, and type.
    • +
  • Only a single action may be provided and must exist for request and response packets.
    • +
  • Only a single status may be provided and must exist for response packets.
    • +
  • The payload is dependent on the action.
    • +
+
+ +
+
+

Packet Documentation

+
+ +
+

+ Describes how a packet is designed and intended to be used. +

+

+ The packet is the general category in which multiple types of packets belong. + This describes the different packets based on their type. +

+

+ Each packet begins with a control block and a size block followed by a payload block. +

+

+ The control block: +

+
    +
  • The leading bit (starting from the left) designates the the format of the payload, which is 0 for string and 1 for binary.
    • +
  • The second bit (starting from the left) designates the the byte order for the rest of the packet, which 0 is for little endian and 1 is for big endian.
    • +
  • The remaining 6-bits are reserved for future use.
    • +
  • +

    + The size block: +

    +
      +
    • The size block represents the size of the entire packet (the control block, the size blocks, and the payload block).
      • +
    • This number is a single 32-bit unsigned integer.
      • +
    +
    • +
  • +

    + Example packet structure: +

    + 
    [ Control Block ] [ Size Block                                  ] [ Payload Block         ]
+[ 0b10000000    ] [ 0b00000000 0b00000000 0b00000100 0b11010010 ] [ size: 1229 (1234 - 5) ]
    +
    • +
  • +

    + The payload block: +

    +

    + This block is represented by the FSS-000E payload specification and its structure ad use is described in the next sections. +

    +

    + The following types of payload are received or sent: +

    +
      +
    1. controller payload.
      2. +
    2. error payload.
      3. +
    3. init payload.
      4. +
    +
    • +
+

+ The controller payload: +

+
    +
  • Commands being sent to the controller and their respective responses utilize a controller payload.
    • +
  • These are pre-defined commands to rules or the controller program itself.
    • +
  • Commands such as starting or stopping some rule, for example.
    • +
  • +
    A controller payload is also sent in response to a controller payload request to represent a success.
    +
      +
    • The now condition designates that the kexec, reboot, or shutdown is to begin immediately.
      • +
    • The at condition designates that the kexec, reboot, or shutdown is to begin once a specific date and time is reached by the system clock.
      • +
    • The in condition designates that the kexec, reboot, or shutdown is to begin once a specific amount of time is passed by the system clock since the execution of this command started.
      • +
    +
    • +
+

+ For these time conditions, different units of time should be supported, such as seconds, days, years as standard time, Time, or UNIX Time (Epoch Time). +

+

+ The normal controller payload commands are any valid Rule Action that performs some action. + This does not include Actions that provide some setting or configuration (such as with_pid). + Some of the supported commands are: freeze, kill, pause, reload, rerun, restart, resume, start, stop, or thaw. + Multiple commands may be sent multiple action headers. + The action headers are order sensitive, executing from top to bottom, and one does not start until the previous successfully completes. +

+

+ Multiple status headers may exist in the response so long as they each match an action in the request. +

+

+ The payload is expected to be empty and have a length of 0 for a request. + The payload may have an FSS-0000 (Basic) format containing a single Object message to represent a message associated with an action. + Multiple message may exist in the response so long as they each match an action in the request. +

+

+ The error payload: +

+
    +
  • The error payload is intended to communicate some sort of failure.
    • +
  • The error payload is only sent in response to some request (and not in response to another response).
    • +
  • The control (the client) is not expected to send error payloads and the controller (the service) should send an error in response to an error payload or ignore it entirely.
    • +
  • The status from the header designates the status code as either a status code name string or a status code number (where a number may have error and warning bits).
    • +
  • The payload will contain a NULL terminated string representing the message used to describe the error.
    • +
+

+ The init payload: +

+
    +
  • The init payload is intended exclusively for the init operation mode and is expected to only be available when running as init.
    • +
  • This is used to provide special actions, namely kexec, reboot, and shutdown.
    • + +
  • The kexec is for booting into another kernel, which may effectively be the same as a reboot (kexec is currently neither supported nor implemented).
    • +
  • The reboot is for rebooting the machine (currently not implemented).
    • +
  • The shutdown is for shutting down the machine (currently not implemented).
    • +
  • These three commands are configurable to fire off based on conditions.
    • +
+
+
+
+
+
+ + diff --git a/documentation/controller/specifications/rule.html b/documentation/controller/specifications/rule.html new file mode 100644 index 0000000..a1b95a2 --- /dev/null +++ b/documentation/controller/specifications/rule.html @@ -0,0 +1,601 @@ + + + + Documentation - Controller - Specification - Rule + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

Controller Rule Specification

+
+ +
+

+ The Rule files follow the FSS-000D (Basic Rule) format with IKI-0000 (Unrestricted). +

+

+ A Rule file name is expected to have the file extension .rule. +

+

+ For each Rule file: +

+
    +
  • The outer most part is a FSS-0002 (Basic List).
    • +
  • The outer most part is a FSS-0002 (Basic List).
    • +
  • The Basic List Object is considered the Rule Type.
    • +
  • The Basic List Content is determined by the specific Rule Type.
    • +
  • The Content for each Rule Type is called the Item.
    • +
  • Each Item Object is the Item Name.
    • +
  • Each Item Content is either the Action or the Setting.
    • +
  • Each Action Object is the Action Name.
    • +
  • Each Action Content are the Action Parameters.
    • +
  • Each Setting Object is the Setting Name.
    • +
  • Each Setting Content are the Setting Values.
    • +
+

+ The Rule Types: +

+
    +
  • command: Follows either FSS-0003 (Extended List) or FSS-0001 (Extended).
    • +
  • script: Follows either FSS-0003 (Extended List) or FSS-0001 (Extended).
    • +
  • service: Follows either FSS-0003 (Extended List) or FSS-0001 (Extended).
    • +
  • settings: Is required and follows either FSS-0001 (Extended).
    • +
  • utility: Follows either FSS-0003 (Extended List) or FSS-0001 (Extended).
    • +
+

+ For the above Rule Types, settings may be specified only once whereas the others may be specifed multiple times. +

+

+ The settings Rule Type is always processed first, regardless of position. +

+

+ The other Rule Types are processed top-down. +

+

+ The settings Rule Type has the following FSS-0001 (Extended): +

+
    +
  • affinity: One or more Content, each must be a 0 or greater whole number.
    • +
  • capability: One Content representing capabilities.
    • +
  • cgroup: Two or more Content, the first Content being either existing or new and the remaining representing a valid cgroup (control group) name, must have at least 1 graph character (non white space printing character) (leading and trailing white space are trimmed off).
    • +
  • define: Two Content, the first Content must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits).
    • +
  • engine: One or more Content representing a valid program name or path (such as bash or /bin/bash) and any optional arguments.
    • +
  • environment: Zero or more Content, each must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits).
    • +
  • group: One or more Content representing group names or group ids.
    • +
  • limit: Three Content, with the first representing a valid resource type and the second and third being a valid resource limit number (positive whole number or 0).
    • +
  • name: One Content, must have at least 1 graph character (non white space printing character) (leading and trailing white space are trimmed off).
    • +
  • nice: One Content, must be a valid number for process niceness (Any whole number inclusively between -20 to 19).
    • +
  • on: Four Content, the first being a Rule Action, the second being need, want, or wish, the third being a partial path, and the fourth being a Rule file name without .rule extension.
    • +
  • parameter: Two Content, the first Content must be a case-sensitive valid IKI name and the second being an IKI value.
    • +
  • path: One Content representing a valid PATH environment string (such as /bin:/sbin:/usr/bin).
    • +
  • scheduler: One or two Content representing a scheduler name and the optional numeric priority (Any whole number inclusively between 0 and 99).
    • +
  • timeout: One or two content with the first being one of exit, start, stop, or kill and the (optional) second Content being a positive whole number or 0.
    • +
  • user: One Content representing a user name or user id.
    • +
+

+ The command and script Rule Types allow the following the FSS-0001 (Extended): +

+
    +
  • freeze: One or more Content representing a program being executed and its arguments.
    • +
  • kill: One or more Content representing a program being executed and its arguments.
    • +
  • pause: One or more Content representing a program being executed and its arguments.
    • +
  • reload: One or more Content representing a program being executed and its arguments.
    • +
  • rerun: Two or more Content representing a Rule type that executes and its properties.
    • +
  • restart: One or more Content representing a program being executed and its arguments.
    • +
  • resume: One or more Content representing a program being executed and its arguments.
    • +
  • start: One or more Content representing a program being executed and its arguments.
    • +
  • stop: One or more Content representing a program being executed and its arguments.
    • +
  • thaw: One or more Content representing a program being executed and its arguments.
    • +
  • with: One or more Content representing special options for the Rule Type.
    • +
+

+ The service and utility Rule Types allow the following the FSS-0001 (Extended): +

+
    +
  • pid_file: One Content representing the path to a PID file.
    • +
  • rerun: Two or more Content representing a Rule type that executes and its properties.
    • +
  • with: One or more Content being one of full_path, session_new, or session_same.
    • +
+

+ The command and service Rule Types allow the following the FSS-0003 (Extended List): +

+
    +
  • freeze: A list repesenting multiple programs and their respective arguments to execute.
    • +
  • kill: A list repesenting multiple programs and their respective arguments to execute.
    • +
  • pause: A list repesenting multiple programs and their respective arguments to execute.
    • +
  • reload: A list repesenting multiple programs and their respective arguments to execute.
    • +
  • restart: A list repesenting multiple programs and their respective arguments to execute.
    • +
  • resume: A list repesenting multiple programs and their respective arguments to execute.
    • +
  • start: A list repesenting multiple programs and their respective arguments to execute.
    • +
  • stop: A list repesenting multiple programs and their respective arguments to execute.
    • +
  • thaw: A list repesenting multiple programs and their respective arguments to execute.
    • +
+

+ The script and utility Rule Types allow the following the FSS-0003 (Extended List): +

+
    +
  • freeze: A list repesenting the contents of a script, such as a GNU Bash shell.
    • +
  • kill: A list repesenting the contents of a script, such as a GNU Bash shell.
    • +
  • pause: A list repesenting the contents of a script, such as a GNU Bash shell.
    • +
  • reload: A list repesenting the contents of a script, such as a GNU Bash shell.
    • +
  • restart: A list repesenting the contents of a script, such as a GNU Bash shell.
    • +
  • resume: A list repesenting the contents of a script, such as a GNU Bash shell.
    • +
  • start: A list repesenting the contents of a script, such as a GNU Bash shell.
    • +
  • stop: A list repesenting the contents of a script, such as a GNU Bash shell.
    • +
  • thaw: A list repesenting the contents of a script, such as a GNU Bash shell.
    • +
+

+ The rerun Rule Type Content has the following structure. +

+
    +
  • The first Content represents one of: freeze, kill, pause, reload, restart, resume, start, stop, or thaw.
    • +
  • The second Content represents one of: success or failure.
    • +
  • The third and more Content represents one of: delay, max, or reset.
    • +
  • Where delay and max must be followed by a positive number or the number 0.
    • +
+
+ +
+
+

Rule Documentation

+
+ +
+

+ This describes the intent and purpose of a Rule file. +

+

+ A Rule file, such as ssh.rule, is intended to designate what to execute. +

+

+ The rule file is read top-down, except for the outer most list settings, which is intended to store setting data for this rule. + Multiple outer most list Objects may be specified and they are executed as provided, in a top-down manner. +

+

+ The settings Rule Type has the following FSS-0001 (Extended) Content: +

+
    +
  • affinity: Define one or more processors to restrict this rule by with each number representing a specific processor by its id (starting at 0).
    • +
  • capability: Define a set of capabilities in which to use, using the capability text format (such as = cap_chown+ep).
    • +
  • cgroup: Define a cgroup (control group) in which everything within this rule executes under.
    • +
  • define: A single environment variable name and its associated value that is automatically exposed to processes executed within this rule.
    • +
  • engine: An executable name of a script, such as bash, to use for the script Rule Type (which likely defaults to bash if not specified).
    • +
  • environment: A set of environment variables to expose to the processes executed within this rule (PATH is always exposed).
    • +
  • group: A set of group names or IDs to execute as with the first group being the primary group and all remaining being supplementary groups.
    • +
  • limit: Define a resource limit to use (multiple limits may be specified, but only once for each type).
    • +
  • name: A name used to represent this rule, which is printed to the user, screen, logs, etc...
    • +
  • nice: A single niceness value to run all processes executed within this rule as (-20 gets to be greediest in CPU usage and 19 being the nicest in CPU usage).
    • +
  • on: Define a Rule Action in which a specified dependency is needed, wanted, or wished for.
    • +
  • parameter: An IKI name and its associated value for use in this rule file.
    • +
  • path: A single Content used to set a custom PATH environment variable value.
    • +
  • scheduler: A valid name of a scheduler to use followed by an optional priority number.
    • +
  • timeout: A set of timeouts to wait for in which to perform a set action or to consider failure.
    • +
  • user: A single user name or ID to execute as.
    • +
+

+ The capability setting: +

+
    +
  • If the user the controller program is run as does not have the desired capabilities already, they cannot be added.
    • +
  • This essentially maintains or reduces the capabilities already available.
    • +
  • Due to capabilities only being a draft in the POSIX standard, one may expect capabilities support may not be available and in such a case this setting will do nothing.
    • +
  • If the dependent project (f_capability) does not have libcap support enabled, then capabilities will be unsupported by the compilation of this project.
    • +
+

+ The control setting: +

+
    +
  • The first argument is either existing or new, where for existing the process is run inside the existing control used by the parent and when new the process is executed within a new control group namespace entirely.
    • +
+

+ The define setting: +

+
    +
  • Use this to define an environment variable (this overwrites any existing environment variable with this name).
    • +
  • A define is both exported as an environment variable as well as exposed as an IKI variable.
    • +
  • Example IKI variable substitution: for define PATH /bin:/sbin, the associated IKI variable would look like: define:"PATH".
    • +
  • All environment variables, including those defined using this, must be in the environment list to be exported to the executed process.
    • +
  • Environment variables added here that are not added to the environment are still exposed as an IKI variable.
    • +
+

+ The engine setting: +

+
    +
  • This engine is used for both script and utility Rule Types.
    • +
  • The program that engine refers to must accept a standard input pipe to be supported.
    • +
  • Additional parameters may be passed to the engine.
    • +
+

+ The group and user settings: +

+
    +
  • Only users and groups that the user the controller program is being run as is allowed to use may be used.
    • +
+

+ The limit setting: +

+
    +
  • The first parameter must be one of: as, core, cpu, data, fsize, locks, memlock, msgqueue, nice, nofile, nproc, rss, rtprio, rttime, sigpending, or stack.
    • +
  • The second parameter represents the soft limit.
    • +
  • The third parameter represents the hard limit.
    • +
  • This may be specified multiply times, but only once for each type.
    • +
+

+ The on setting: +

+
    +
  • The first parameter represents the Action the dependency exists under and must be one of: freeze, kill, pause, reload, restart, resume, start, stop, or thaw.
    • +
  • The second parameter represents how the dependency is required and must be one of: need, want, or wish.
    • +
  • The third parameter is a partial path to the rule file.
    • +
  • The fourth parameter represents the name of the rule file.
    • +
+

+ In the case of the second parameter: +

+
    +
  • A need designates that the dependent rule is required to be executed (must exist and must succeed).
    • +
  • A want designates that the dependent rule is to be executed (may exist and if it does, then it must succeed).
    • +
  • A wish designates that the dependent rule is to be executed (may exist and if it does, but it does not need to succeed).
    • +
+

+ In the case of want and wish, if the desired rule is either not found or is otherwise disabled, then this will not fail or otherwise block the wanting or wishing rule. +

+

+ The path setting: +

+
    +
  • When specified, the PATH environment variable is automatically added to the environment setting.
    • +
+

+ The parameter setting: +

+
    +
  • Use this to define an IKI variable name and value.
    • +
  • These do not conflict with environment variables and are not exposed as environment variables.
    • +
  • Example IKI variable substitution: for parameter hello world, the associated IKI variable would look like: parameter:"hello".
    • +
+

+ The scheduler setting: +

+
    +
  • The valid range of the priority number is dependent on the scheduler.
    • +
  • For example, non-real-time schedulers (such as idle) only support a value of 0 whereas real-time schedulers (such as fifo) only support an inclusive range of 1 to 99.
    • +
  • Supported non-real-time schedulers are: batch, idle, and other (aka: normal/default).
    • +
  • Supported real-time schedulers are: deadline, fifo, round_robin.
    • +
+

+ The timeout setting: +

+
    +
  • (This is not currently implemented.)
    • +
  • Provides settings for each of the three special situations: kill, start, and stop.
    • +
  • Each of these may only have a single one exist at a time (one kill, one start, and one stop).
    • +
  • Each successive timeout Item Action, specific to each Action Name (such as start), specified replaces the previously defined timeout Action (in a top-down manner).
    • +
  • The second Content for each of these, when specified, may be a 0 or greater whole number representing the number of MegaTime (MT) (equivalent to milliseconds).
    • +
  • For kill, this represents the number of MegaTime to wait after stopping some Rule and that Rule has not yet stopped to forcefully stop the Rule (aka kill the Rule).
    • +
  • For start, this represents the number of MegaTime to wait after starting some Rule before assuming something went wrong and the Rule is returned as failed.
    • +
  • For stop, this represents the number of MegaTime to wait after stopping some Rule before assuming something went wrong and the Rule is returned as failed.
    • +
  • If the second Content is not specified, then this disables the type (prevents the specified timeout action).
    • +
+

+ There are four available Rule Types to choose from: command, service, script, and utility. +

+

+ The command Rule Type provides a simple command to run under the different circumstances: start, stop, restart, and reload. + A command always operates in the foreground. +

+

+ The service Rule Type provides a command accompanied with a PID file (Process Identifier file). +

+

+ The script Rule Type provides a series of lines to be executed by some engine, such as GNU Bash. + This script operates in the foreground, but individual things done within the script may operate in foreground or background. + The last return state is treated as an error, so be sure to finish the script with a return code of 0 to designate no error and any other whole number, such a 1, to designate an error. + Therefore passing exit 1 would return as an error and passing exit 0 would return as a success. + A script is assumed to be in GNU Bash, which is the default expected behavior, but the specification does not explicitly require this. + Another scripting language can be used but changing this incurs the responsibility to ensure all rules are updated to the appropriate scripting language. +

+

+ The utility Rule Type provides a script accompanied with a PID file (Process Identifier file). +

+

+ There are nine Rule Actions used to execute (freeze, kill, pause, reload, restart, resume, start, stop, and thaw): +

+

+ When restart Object's Content is not provided, then start and stop is called when the rule is executed using the restart Action, if both start and stop are provided. +

+

+ When reload, start, or stop Object's Content are not provided, then no respective Action is performed. +

+

+ Commands are conditionally available depending on the presence of these, such as if stop is not provided then stop (and restart) will not be available for the control program(s) to use. +

+

+ Thee are additional Rule Actions not used to execute (pid_file, rerun, and with): +

+
    +
  • The pid_file Object's Content designates the path to the PID file created by the called program.
    • +
  • +
    The rerun Object's Content designates how to re-run a given execution Rule type.
    +
      +
    • The first Content represents the execution type, which may be one of: freeze, kill, pause, reload, restart, resume, start, stop, and thaw.
      • +
    • The second Content represents when to run this re-run is triggered, which is either success (return code of 0) or failure (return code is not 0).
      • +
    • +
      The third Content and more represent additional options for fine tuning how the re-run is Performed:
      +
        +
      • When delay, followed by a number of MegaTime (MT) (equivalent to milliseconds) in which to wait before attempting the re-run.
        • +
      • When max, followed by a positive number or the number 0 designating the maximum number of re-runs to perform.
        • +
      • +
        When reset, the max re-run counter is reset for the opposite re-run when this re-run is triggered, such as:
        +
          +
        • A rerun start success reset and a rerun failure max 10, the failure counter would reset to 0 when the success re-run is performed and not when the failure re-run is performed.
          • +
        +
        • +
      +
      • +
    • A max of 0 designates that the re-run will happen infinitely.
      • +
    +
    • +
  • +
    The with Object's Content designates special flags designating very specific behavior to be applied to any single Rule Type.
    +
      +
    • +
      The following flags are supported:
      +
        +
      • full_path: Used only by Rule Types that execute something, wherein the entire full path is used for execution and is assigned as argument[0] (such as /bin/bash).
        • +
      • When not specified, the path provided is used and the argument[0] will be the base name (such as bash).
        • +
      • session_new: Execute in a new session setting the process group to the executed process' id (making the executed process a controlling terminal).
        • +
      • session_same: Execute in the same session where the process group is set to the parent process id.
        • +
      +
      • +
    +
    • +
+

+ IKI Variables: +

+
    +
  • All Rule Actions support IKI variable substitution.
    • +
  • The Rule Settings do not support IKI variable substitution.
    • +
  • +
    The following IKI variable names are supported:
    +
      +
    • define
      • +
    • parameter
      • +
    • program
      • +
    +

    + The define IKI variables, such as define:"PATH", expand environment variables. +

    +

    + The parameter IKI variables, such as parameter:"hello", expand IKI variables defined using the parameter Setting Rule Type. +

    +

    + The program IKI variables, such as program:"verbose:option", expand program arguments (where verbose:option might expand into -v ). +

    +

    + Only the following program IKI variables are supported: +

    +
      +
    • +
      dark:
      +
        +
      • This variable holds the dark program parameters, such as +d.
        • +
      • This supports :option.
        • +
      +
      • +
    • +
      light:
      +
        +
      • This variable holds the light program parameters, such as +l.
        • +
      • This supports :option.
        • +
      +
      • +
    • +
      no_color:
      +
        +
      • This variable holds the no_color program parameters, such as +n.
        • +
      • This supports :option.
        • +
      +
      • +
    • +
      quiet:
      +
        +
      • This variable holds the quiet program parameters, such as +Q.
        • +
      • This supports :option.
        • +
      +
      • +
    • +
      error:
      +
        +
      • This variable holds the error program parameters, such as +E.
        • +
      • This supports :option.
        • +
      +
      • +
    • +
      normal:
      +
        +
      • This variable holds the normal program parameters, such as +N.
        • +
      • This supports :option.
        • +
      +
      • +
    • +
      verbose:
      +
        +
      • This variable holds the verbose program parameters, such as +V.
        • +
      • This supports :option.
        • +
      +
      • +
    • +
      debug:
      +
        +
      • This variable holds the debug program parameters, such as +D.
        • +
      • This supports :option.
        • +
      +
      • +
    • +
      cgroup:
      +
        +
      • This variable holds the cgroup program parameters, such as -c /sys/fs/cgroup/.
        • +
      • This supports both :option and :value.
        • +
      +
      • +
    • +
      daemon:
      +
        +
      • This variable holds the daemon program parameters, such as -d.
        • +
      • This supports :option.
        • +
      +
    • +
      init: +
        +
      • This variable holds the init program parameters, such as -I.
        • +
      • This supports :option.
        • +
      +
    • +
      interruptible: +
        +
      • This variable holds the interruptible program parameters, such as -i.
        • +
      • This supports :option.
        • +
      +
    • +
      pid: +
        +
      • This variable holds the pid program parameters, such as -p controller/run/default.pid.
        • +
      • This supports both :option and :value.
        • +
      +
    • +
      settings: +
        +
      • This variable holds the settings program parameters, such as -s controller/.
        • +
      • This supports both :option and :value.
        • +
      +
    • +
      simulate: +
        +
      • This variable holds the simulate program parameters, such as -S.
        • +
      • This supports :option.
        • +
          +
        • +
          socket: +
            +
          • This variable holds the socket program parameters, such as -k controller/run/default.socket.
            • +
          • This supports both :option and :value.
            • +
          +
        • +
          uninterruptible: +
            +
          • This variable holds the uninterruptible program parameters, such as -U.
            • +
          • This supports :option.
            • +
          +
        • +
          validate: +
            +
          • This variable holds the validate program parameters, such as -v.
            • +
          • This supports :option.
            • +
          +
          • +
        + +
      +
      +
+
+
+
+ + diff --git a/documentation/fake.html b/documentation/fake.html index b109471..98f44f2 100644 --- a/documentation/fake.html +++ b/documentation/fake.html @@ -52,14 +52,11 @@
Back
-
+
Documentation
Featureless Make
- About -
-
Standard Parameters
@@ -70,6 +67,7 @@
Specifications
+ Featureless Make
APIs
@@ -86,42 +84,36 @@

Featureless Make Documentation

-
-
-

About

-
- -
-

- The fake program, also called Featureless Make is the flagship program of the FLL project and provides the ability to compile source code and perform various actions not unlike how the GNU Make program operates. -

-

- This tools is directly intended to be a replacement to the GNU Make program but not as a replacement for all of the GNU Make functionality. Instead, the fake program follows the ideology that a build program should not involve itself with system-specific behavior, such as installing to a system. -

-

- Despite this non-standard ideology, the fake program is flexible enough to be used as an installer. In fact, this tool is used to not only build the entire FLL but it can also compile and run unit tests for the project. -

-

- A bootstrap script is provided in all FLL projects that operates with almost complete one-to-one functionality to this tool to allow for the system to build itself. A great example of this is the test script used to run unit tests on services like Github where this project must compile itself and then use itself to run unit tests against itself. -

-

- While most of the programs provided with the FLL are young and not well tested, the fake program is considered mature. -

-

- There are two primary operations in which this tool executes: -

-
    -
  1. The build operation.
    2. -
  2. The make operation.
    3. -
-

- The build mode is derived from the idea that most of the compilation process is redundant and can be simplified to a pre-define set of configuration settings. This reduces the amount of efforted needed to write and mainting a build system at the cost of flexibility. -

-

- The make mode is the mode for operating as a replacement to the GNU Make program. This provides scriptable ways to perform just about any task needed when building a system. Many of the build mode settings are available (but are not required) and this mode can even call the build mode itself. -

-
-
+
+

+ The fake program, also called Featureless Make is the flagship program of the FLL project and provides the ability to compile source code and perform various actions not unlike how the GNU Make program operates. +

+

+ This tools is directly intended to be a replacement to the GNU Make program but not as a replacement for all of the GNU Make functionality. Instead, the fake program follows the ideology that a build program should not involve itself with system-specific behavior, such as installing to a system. +

+

+ Despite this non-standard ideology, the fake program is flexible enough to be used as an installer. In fact, this tool is used to not only build the entire FLL but it can also compile and run unit tests for the project. +

+

+ A bootstrap script is provided in all FLL projects that operates with almost complete one-to-one functionality to this tool to allow for the system to build itself. A great example of this is the test script used to run unit tests on services like Github where this project must compile itself and then use itself to run unit tests against itself. +

+

+ While most of the programs provided with the FLL are young and not well tested, the fake program is considered mature. +

+

+ There are two primary operations in which this tool executes: +

+
    +
  1. The build operation.
    2. +
  2. The make operation.
    3. +
+

+ The build mode is derived from the idea that most of the compilation process is redundant and can be simplified to a pre-define set of configuration settings. This reduces the amount of efforted needed to write and mainting a build system at the cost of flexibility. +

+

+ The make mode is the mode for operating as a replacement to the GNU Make program. This provides scriptable ways to perform just about any task needed when building a system. Many of the build mode settings are available (but are not required) and this mode can even call the build mode itself. +

+
diff --git a/documentation/fake/specifications.html b/documentation/fake/specifications.html new file mode 100644 index 0000000..e2e605a --- /dev/null +++ b/documentation/fake/specifications.html @@ -0,0 +1,98 @@ + + + + Documentation - Featureless Make - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

Featureless Make Specifications

+
+ +
+

+ The FLL project provides several specifications. + The Featureless Make does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/firewall.html b/documentation/firewall.html index 67e3c52..c7bfc0e 100644 --- a/documentation/firewall.html +++ b/documentation/firewall.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
Firewall
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ Firewall
APIs
@@ -84,23 +82,17 @@

Firewall Documentation

-
-
-

About

-
- -
-

- The firewall program is a tool for simplifying and automating the iptables program. -

-

- This tool is set to be replaced now that both the firewall and the iptables programs are outdated. The latest iptables program replacement (the nftables program) is superior and the firewall will need major rewrites to utilize the replacement. -

-

- This tools is one of the original two programs of the FLL project and is designed to be a fully functional proof of concept for the FLL project. -

-
-
+
+

+ The firewall program is a tool for simplifying and automating the iptables program. +

+

+ This tool is set to be replaced now that both the firewall and the iptables programs are outdated. The latest iptables program replacement (the nftables program) is superior and the firewall will need major rewrites to utilize the replacement. +

+

+ This tools is one of the original two programs of the FLL project and is designed to be a fully functional proof of concept for the FLL project. +

+
diff --git a/documentation/firewall/specifications.html b/documentation/firewall/specifications.html new file mode 100644 index 0000000..96e35cd --- /dev/null +++ b/documentation/firewall/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - Firewall - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

Firewall Specifications

+
+ +
+

+ The FLL project provides several specifications. + The Firewall does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_basic_list_read.html b/documentation/fss_basic_list_read.html index 5e468cf..6ba48fe 100644 --- a/documentation/fss_basic_list_read.html +++ b/documentation/fss_basic_list_read.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Basic List Read
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Basic List Read
APIs
@@ -83,23 +81,17 @@

FSS Basic List Read Documentation

-
-
-

About

-
- -
-

- The fss_basic_list_read program is a tool for reading and processing strings that follow the FSS-0002 (Basic List) standard. -

-

- This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. -

-

- This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. -

-
-
+
+

+ The fss_basic_list_read program is a tool for reading and processing strings that follow the FSS-0002 (Basic List) standard. +

+

+ This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. +

+

+ This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. +

+
diff --git a/documentation/fss_basic_list_read/specifications.html b/documentation/fss_basic_list_read/specifications.html new file mode 100644 index 0000000..9d6bbaa --- /dev/null +++ b/documentation/fss_basic_list_read/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Basic List Read - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

FSS Basic List Read Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Basic List Read does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_basic_list_write.html b/documentation/fss_basic_list_write.html index e80485a..5ffd012 100644 --- a/documentation/fss_basic_list_write.html +++ b/documentation/fss_basic_list_write.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Basic List Write
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Basic List Write
APIs
@@ -84,23 +82,17 @@

FSS Basic List Write Documentation

-
-
-

About

-
- -
-

- The fss_basic_list_write program is a tool for generating strings that follow the FSS-0002 (Basic List) standard. -

-

- This tool is designed to be scriptable and accepts piped input using a special format. -

-

- This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. -

-
-
+
+

+ The fss_basic_list_write program is a tool for generating strings that follow the FSS-0002 (Basic List) standard. +

+

+ This tool is designed to be scriptable and accepts piped input using a special format. +

+

+ This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. +

+
@@ -262,7 +254,7 @@ For the pipe, an Object is terminated by either a Backspace character '\b' (U+0008) or a Form Feed character '\f' (U+000C). The end of the pipe represents the end of any Object or Content.

- The FSS-0002 (Basic List) specification does not support quoted names, therefore the parameters --single and --double do nothing. + The FSS-0002 (Basic List) specification does not support quoted names, therefore the parameters --single and --double do nothing.

This program does not use the parameter --ignore, which therefore does nothing. This parameter requires two values. diff --git a/documentation/fss_basic_list_write/specifications.html b/documentation/fss_basic_list_write/specifications.html new file mode 100644 index 0000000..65439a6 --- /dev/null +++ b/documentation/fss_basic_list_write/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Basic List Write - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +
+ + +
+
+
+

FSS Basic List Write Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Basic List Write does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_basic_read.html b/documentation/fss_basic_read.html index 88db2ea..37b01d4 100644 --- a/documentation/fss_basic_read.html +++ b/documentation/fss_basic_read.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Basic Read
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Basic Read
APIs
@@ -84,23 +82,17 @@

FSS Basic Read Documentation

-
-
-

About

-
- -
-

- The fss_basic_read program is a tool for reading and processing strings that follow the FSS-0000 (Basic) standard. -

-

- This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. -

-

- This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. -

-
-
+
+

+ The fss_basic_read program is a tool for reading and processing strings that follow the FSS-0000 (Basic) standard. +

+

+ This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. +

+

+ This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. +

+
diff --git a/documentation/fss_basic_read/specifications.html b/documentation/fss_basic_read/specifications.html new file mode 100644 index 0000000..3cce935 --- /dev/null +++ b/documentation/fss_basic_read/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Basic Read - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

FSS Basic Read Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Basic Read does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_basic_write.html b/documentation/fss_basic_write.html index 112991d..4332d1f 100644 --- a/documentation/fss_basic_write.html +++ b/documentation/fss_basic_write.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Basic Write
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Basic Write
APIs
@@ -84,23 +82,17 @@

FSS Basic Write Documentation

-
-
-

About

-
- -
-

- The fss_basic_write program is a tool for generating strings that follow the FSS-0000 (Basic) standard. -

-

- This tool is designed to be scriptable and accepts piped input using a special format. -

-

- This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. -

-
-
+
+

+ The fss_basic_write program is a tool for generating strings that follow the FSS-0000 (Basic) standard. +

+

+ This tool is designed to be scriptable and accepts piped input using a special format. +

+

+ This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. +

+
@@ -262,7 +254,7 @@ For the pipe, an Object is terminated by either a Backspace character '\b' (U+0008) or a Form Feed character '\f' (U+000C). The end of the pipe represents the end of any Object or Content.

- The FSS-0000 (Basic) specification does not support multi-line Content, therefore the parameter --prepend does nothing. + The FSS-0000 (Basic) specification does not support multi-line Content, therefore the parameter --prepend does nothing.

This program does not use the parameter --ignore, which therefore does nothing. This parameter requires two values. diff --git a/documentation/fss_basic_write/specifications.html b/documentation/fss_basic_write/specifications.html new file mode 100644 index 0000000..356cdb7 --- /dev/null +++ b/documentation/fss_basic_write/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Basic Write - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +
+ + +
+
+
+

FSS Basic Write Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Basic Write does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_embedded_list_read.html b/documentation/fss_embedded_list_read.html index f0349a2..a40cd42 100644 --- a/documentation/fss_embedded_list_read.html +++ b/documentation/fss_embedded_list_read.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Embedded List Read
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Embedded List Read
APIs
@@ -84,23 +82,17 @@

FSS Embedded List Read Documentation

-
-
-

About

-
- -
-

- The fss_embedded_list_read program is a tool for reading and processing strings that follow the FSS-0008 (Embedded List) standard. -

-

- This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. -

-

- This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. -

-
-
+
+

+ The fss_embedded_list_read program is a tool for reading and processing strings that follow the FSS-0008 (Embedded List) standard. +

+

+ This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. +

+

+ This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. +

+
diff --git a/documentation/fss_embedded_list_read/specifications.html b/documentation/fss_embedded_list_read/specifications.html new file mode 100644 index 0000000..e11de26 --- /dev/null +++ b/documentation/fss_embedded_list_read/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Embedded List Read - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

FSS Embedded List Read Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Embedded List Read does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_embedded_list_write.html b/documentation/fss_embedded_list_write.html index 2ed11a2..657ef43 100644 --- a/documentation/fss_embedded_list_write.html +++ b/documentation/fss_embedded_list_write.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Embedded List Write
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Embedded List Write
APIs
@@ -84,23 +82,17 @@

FSS Embedded List Write Documentation

-
-
-

About

-
- -
-

- The fss_embedded_list_write program is a tool for generating strings that follow the FSS-0008 (Embedded List) standard. -

-

- This tool is designed to be scriptable and accepts piped input using a special format. -

-

- This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. -

-
-
+
+

+ The fss_embedded_list_write program is a tool for generating strings that follow the FSS-0008 (Embedded List) standard. +

+

+ This tool is designed to be scriptable and accepts piped input using a special format. +

+

+ This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. +

+
@@ -262,7 +254,7 @@ For the pipe, an Object is terminated by either a Backspace character '\b' (U+0008) or a Form Feed character '\f' (U+000C). The end of the pipe represents the end of any Object or Content.

- The FSS-0008 (Embedded List) specification does not support quoted names, therefore the parameters --single and --double do nothing. + The FSS-0008 (Embedded List) specification does not support quoted names, therefore the parameters --single and --double do nothing.

This program uses the parameter --ignore, which designates to not escape any valid nested Object or Content within some Content. This parameter requires two values. This parameter is not used for ignoring anything from the input pipe. This parameter must be specified after a --content parameter and this applies only to the Content represented by that specific --content parameter. diff --git a/documentation/fss_embedded_list_write/specifications.html b/documentation/fss_embedded_list_write/specifications.html new file mode 100644 index 0000000..c9e326d --- /dev/null +++ b/documentation/fss_embedded_list_write/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Embedded List Write - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +
+ + +
+
+
+

FSS Embedded List Write Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Embedded List Write does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_extended_list_read.html b/documentation/fss_extended_list_read.html index 0de1252..b70f146 100644 --- a/documentation/fss_extended_list_read.html +++ b/documentation/fss_extended_list_read.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Extended List Read
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Extended List Read
APIs
@@ -84,23 +82,17 @@

FSS Extended List Read Documentation

-
-
-

About

-
- -
-

- The fss_extended_list_read program is a tool for reading and processing strings that follow the FSS-0003 (Extended List) standard. -

-

- This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. -

-

- This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. -

-
-
+
+

+ The fss_extended_list_read program is a tool for reading and processing strings that follow the FSS-0003 (Extended List) standard. +

+

+ This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. +

+

+ This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. +

+
diff --git a/documentation/fss_extended_list_read/specifications.html b/documentation/fss_extended_list_read/specifications.html new file mode 100644 index 0000000..f145987 --- /dev/null +++ b/documentation/fss_extended_list_read/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Extended List Read - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

FSS Extended List Read Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Extended List Read does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_extended_list_write.html b/documentation/fss_extended_list_write.html index 814bddd..b986a43 100644 --- a/documentation/fss_extended_list_write.html +++ b/documentation/fss_extended_list_write.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Extended List Write
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Extended List Write
APIs
@@ -84,23 +82,17 @@

FSS Extended List Write Documentation

-
-
-

About

-
- -
-

- The fss_extended_list_write program is a tool for generating strings that follow the FSS-0003 (Extended List) standard. -

-

- This tool is designed to be scriptable and accepts piped input using a special format. -

-

- This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. -

-
-
+
+

+ The fss_extended_list_write program is a tool for generating strings that follow the FSS-0003 (Extended List) standard. +

+

+ This tool is designed to be scriptable and accepts piped input using a special format. +

+

+ This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. +

+
@@ -262,7 +254,7 @@ For the pipe, an Object is terminated by either a Backspace character '\b' (U+0008) or a Form Feed character '\f' (U+000C). The end of the pipe represents the end of any Object or Content.

- The FSS-0003 (Extended List) specification does not support quoted names, therefore the parameters --single and --double do nothing. + The FSS-0003 (Extended List) specification does not support quoted names, therefore the parameters --single and --double do nothing.

This program uses the parameter --ignore, which designates to not escape any valid nested Object or Content within some Content. This parameter requires two values. This parameter is not used for ignoring anything from the input pipe. This parameter must be specified after a --content parameter and this applies only to the Content represented by that specific --content parameter. diff --git a/documentation/fss_extended_list_write/specifications.html b/documentation/fss_extended_list_write/specifications.html new file mode 100644 index 0000000..852e9e8 --- /dev/null +++ b/documentation/fss_extended_list_write/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Extended List Write - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +
+ + +
+
+
+

FSS Extended List Write Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Extended List Write does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_extended_read.html b/documentation/fss_extended_read.html index 457c912..f7c418f 100644 --- a/documentation/fss_extended_read.html +++ b/documentation/fss_extended_read.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Extended Read
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Extended Read
APIs
@@ -84,23 +82,17 @@

FSS Extended Read Documentation

-
-
-

About

-
- -
-

- The fss_extended_read program is a tool for reading and processing strings that follow the FSS-0001 (Extended) standard. -

-

- This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. -

-

- This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. -

-
-
+
+

+ The fss_extended_read program is a tool for reading and processing strings that follow the FSS-0001 (Extended) standard. +

+

+ This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. +

+

+ This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. +

+
diff --git a/documentation/fss_extended_read/specifications.html b/documentation/fss_extended_read/specifications.html new file mode 100644 index 0000000..ca373dc --- /dev/null +++ b/documentation/fss_extended_read/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Extended Read - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

FSS Extended Read Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Extended Read does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_extended_write.html b/documentation/fss_extended_write.html index a451d8d..8f6141a 100644 --- a/documentation/fss_extended_write.html +++ b/documentation/fss_extended_write.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Extended Write
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Extended Write
APIs
@@ -83,23 +81,17 @@

FSS Extended Write Documentation

-
-
-

About

-
- -
-

- The fss_extended_write program is a tool for generating strings that follow the FSS-0001 (Extended) standard. -

-

- This tool is designed to be scriptable and accepts piped input using a special format. -

-

- This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. -

-
-
+
+

+ The fss_extended_write program is a tool for generating strings that follow the FSS-0001 (Extended) standard. +

+

+ This tool is designed to be scriptable and accepts piped input using a special format. +

+

+ This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. +

+
@@ -261,7 +253,7 @@ For the pipe, an Object is terminated by either a Backspace character '\b' (U+0008) or a Form Feed character '\f' (U+000C). The end of the pipe represents the end of any Object or Content.

- The FSS-0001 (Extended) specification does not support multi-line Content, therefore the parameter --prepend does nothing. + The FSS-0001 (Extended) specification does not support multi-line Content, therefore the parameter --prepend does nothing.

This program does not use the parameter --ignore, which therefore does nothing. This parameter requires two values. diff --git a/documentation/fss_extended_write/specifications.html b/documentation/fss_extended_write/specifications.html new file mode 100644 index 0000000..fe922e0 --- /dev/null +++ b/documentation/fss_extended_write/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Extended Write - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +
+ + +
+
+
+

FSS Extended Write Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Extended Write does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_identify.html b/documentation/fss_identify.html index 3a1a36f..98722fc 100644 --- a/documentation/fss_identify.html +++ b/documentation/fss_identify.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Identify
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Identify
APIs
@@ -84,23 +82,17 @@

FSS Identify Documentation

-
-
-

About

-
- -
-

- The fss_identify program is a tool for processing strings in an attempt to identify the FSS file format based on FSS header comments. -

-

- This program doesn't perforrm any special heuristic. It only checks for the special FSS header and reports what it finds. -

-

- This tool is designed to be scriptable but does not accept piped input. -

-
-
+
+

+ The fss_identify program is a tool for processing strings in an attempt to identify the FSS file format based on FSS header comments. +

+

+ This program doesn't perforrm any special heuristic. It only checks for the special FSS header and reports what it finds. +

+

+ This tool is designed to be scriptable but does not accept piped input. +

+
@@ -236,7 +228,7 @@ When specifying the --total parameter, neither the --object nor the --content parameter may be specified.

- An FSS file is identified by the format "# Object-Content" where the Object, is a machine-name representing the name and may only consist of "word" characters and the Content is a 4-digit hexidecimal number representing a particular variant of the Object. This identifier, if provided, must exist on the first line in a file and must begin with the pound character: "#". White space must follow this pound character. There may be multiple Object and Content pairs, separated by white space, such as: "# fss-0002 fss-0000 iki-0002". + An FSS file is identified by the format "# Object-Content" where the Object, is a machine-name representing the name and may only consist of "word" characters and the Content is a 4-digit hexidecimal number representing a particular variant of the Object. This identifier, if provided, must exist on the first line in a file and must begin with the pound character: "#". White space must follow this pound character. There may be multiple Object and Content pairs, separated by white space, such as: "# FSS-0002 FSS-0000 iki-0002".

diff --git a/documentation/fss_identify/specifications.html b/documentation/fss_identify/specifications.html new file mode 100644 index 0000000..d2eba1a --- /dev/null +++ b/documentation/fss_identify/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Identify - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

FSS Identify Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Identify does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_payload_read.html b/documentation/fss_payload_read.html index 846592b..ca2e490 100644 --- a/documentation/fss_payload_read.html +++ b/documentation/fss_payload_read.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Payload Read
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Payload Read
APIs
@@ -84,23 +82,17 @@

FSS Payload Read Documentation

-
-
-

About

-
- -
-

- The fss_payload_read program is a tool for reading and processing strings that follow the FSS-000E (Payload) standard. -

-

- This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. -

-

- This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. -

-
-
+
+

+ The fss_payload_read program is a tool for reading and processing strings that follow the FSS-000E (Payload) standard. +

+

+ This tool is designed to be scriptable and accepts piped input, treating the piped input as a file being read. +

+

+ This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. +

+
@@ -376,7 +368,7 @@ As an exceptional case, a --depth of 1 applies only to the explicit Object of "header".

- Content at this depth is processed as FSS-0001 (Extended). + Content at this depth is processed as FSS-0001 (Extended).

The Content of the explicit Object of 'payload' will not contain any Content close pipe control codes when using --pipe. diff --git a/documentation/fss_payload_read/specifications.html b/documentation/fss_payload_read/specifications.html new file mode 100644 index 0000000..2d9b2ba --- /dev/null +++ b/documentation/fss_payload_read/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Payload Read - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +
+ + +
+
+
+

FSS Payload Read Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Payload Read does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_payload_write.html b/documentation/fss_payload_write.html index c5d8870..dec43f3 100644 --- a/documentation/fss_payload_write.html +++ b/documentation/fss_payload_write.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Payload Write
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Payload Write
APIs
@@ -84,23 +82,17 @@

FSS Payload Write Documentation

-
-
-

About

-
- -
-

- The fss_payload_write program is a tool for generating strings that follow the FSS-000E (Payload) standard. -

-

- This tool is designed to be scriptable and accepts piped input using a special format. -

-

- This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. -

-
-
+
+

+ The fss_payload_write program is a tool for generating strings that follow the FSS-000E (Payload) standard. +

+

+ This tool is designed to be scriptable and accepts piped input using a special format. +

+

+ This tool shares parameters between with the other FSS Read and Write programs to make scripting consistent across the FSS Read and Write programs even if any given program neither needs nor uses the parameter. +

+
@@ -262,7 +254,7 @@ For the pipe, an Object is terminated by either a Backspace character '\b' (U+0008) or a Form Feed character '\f' (U+000C). The end of the pipe represents the end of any Object or Content.

- The FSS-000E (Payload) specification does not support quoted names, therefore the parameters --single and --double do nothing. + The FSS-000E (Payload) specification does not support quoted names, therefore the parameters --single and --double do nothing.

This program does not use the parameter --ignore, which therefore does nothing. This parameter requires two values. diff --git a/documentation/fss_payload_write/specifications.html b/documentation/fss_payload_write/specifications.html new file mode 100644 index 0000000..4665d6f --- /dev/null +++ b/documentation/fss_payload_write/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Payload Write - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +
+ + +
+
+
+

FSS Payload Write Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Payload Write does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/fss_status_code.html b/documentation/fss_status_code.html index 4c781d7..1648ee0 100644 --- a/documentation/fss_status_code.html +++ b/documentation/fss_status_code.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
FSS Status Code
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ FSS Status Code
APIs
@@ -84,20 +82,14 @@

FSS Status Code Documentation

-
-
-

About

-
- -
-

- The fss_status_code program is a tool for interpretting and changing the status codes received from programs into code words or vice-versa. This is intended to be easily scriptable. The code words are still machine-friendly and scriptable. -

-

- This program handles standard FLL status codes as well as FSS status codes. The max status code supported is represented by the code words F_fss_status_code_last. -

-
-
+
+

+ The fss_status_code program is a tool for interpretting and changing the status codes received from programs into code words or vice-versa. This is intended to be easily scriptable. The code words are still machine-friendly and scriptable. +

+

+ This program handles standard FLL status codes as well as FSS status codes. The max status code supported is represented by the code words F_fss_status_code_last. +

+
diff --git a/documentation/fss_status_code/specifications.html b/documentation/fss_status_code/specifications.html new file mode 100644 index 0000000..078da63 --- /dev/null +++ b/documentation/fss_status_code/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - FSS Status Code - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

FSS Status Code Specifications

+
+ +
+

+ The FLL project provides several specifications. + The FSS Status Code does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/iki_read.html b/documentation/iki_read.html index 1aaaa07..8818c6b 100644 --- a/documentation/iki_read.html +++ b/documentation/iki_read.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
IKI Read
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ IKI Read
APIs
@@ -84,26 +82,20 @@

IKI Read Documentation

-
-
-

About

-
- -
-

- The iki_read program is a tool for processing strings that follow the IKI standard, specifically IKI-0000 (Unrestricted). -

-

- This tool is designed to be scriptable and accepts piped input. -

-

- Different ways of interpreting and printing strings are available. -

-

- The entire string can be printed, replacing all IKI Variables and even allowing for primitive substitution or only the IKI Variables (or their Content) can be printed. -

-
-
+
+

+ The iki_read program is a tool for processing strings that follow the IKI standard, specifically IKI-0000 (Unrestricted). +

+

+ This tool is designed to be scriptable and accepts piped input. +

+

+ Different ways of interpreting and printing strings are available. +

+

+ The entire string can be printed, replacing all IKI Variables and even allowing for primitive substitution or only the IKI Variables (or their Content) can be printed. +

+
diff --git a/documentation/iki_read/specifications.html b/documentation/iki_read/specifications.html new file mode 100644 index 0000000..b497b57 --- /dev/null +++ b/documentation/iki_read/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - IKI Read - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

IKI Read Specifications

+
+ +
+

+ The FLL project provides several specifications. + The IKI Read does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/iki_write.html b/documentation/iki_write.html index 5126456..c449ae9 100644 --- a/documentation/iki_write.html +++ b/documentation/iki_write.html @@ -8,7 +8,7 @@ - + @@ -51,14 +51,11 @@
Back
-
+
Documentation
IKI Write
- About -
-
Standard Parameters
@@ -66,6 +63,7 @@
Specifications
+ IKI Write
APIs
@@ -83,20 +81,14 @@

IKI Write Documentation

-
-
-

About

-
- -
-

- The iki_write program is a tool for generating strings that follow the IKI standard, specifically the IKI-0000 (Unrestricted) standard. -

-

- This tool is designed to be scriptable and accepts piped input using a special format. -

-
-
+
+

+ The iki_write program is a tool for generating strings that follow the IKI standard, specifically the IKI-0000 (Unrestricted) standard. +

+

+ This tool is designed to be scriptable and accepts piped input using a special format. +

+
diff --git a/documentation/iki_write/specifications.html b/documentation/iki_write/specifications.html new file mode 100644 index 0000000..0dec0ba --- /dev/null +++ b/documentation/iki_write/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - IKI Write - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

IKI Write Specifications

+
+ +
+

+ The FLL project provides several specifications. + The IKI Write does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/status_code.html b/documentation/status_code.html index 4a7ccd0..f51c7c6 100644 --- a/documentation/status_code.html +++ b/documentation/status_code.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
Status Code
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ Status Code
APIs
@@ -84,20 +82,14 @@

Status Code Documentation

-
-
-

About

-
- -
-

- The status_code program is a tool for interpretting and changing the status codes received from programs into code words or vice-versa. This is intended to be easily scriptable. The code words are still machine-friendly and scriptable. -

-

- This tool only handles standard FLL status codes. The max status code supported is represented by the code words F_status_code_last. -

-
-
+
+

+ The status_code program is a tool for interpretting and changing the status codes received from programs into code words or vice-versa. This is intended to be easily scriptable. The code words are still machine-friendly and scriptable. +

+

+ This tool only handles standard FLL status codes. The max status code supported is represented by the code words F_status_code_last. +

+
diff --git a/documentation/status_code/specifications.html b/documentation/status_code/specifications.html new file mode 100644 index 0000000..6684cd8 --- /dev/null +++ b/documentation/status_code/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - Status Code - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

Status Code Specifications

+
+ +
+

+ The FLL project provides several specifications. + The Status Code does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documentation/utf8.html b/documentation/utf8.html index 670e581..6159033 100644 --- a/documentation/utf8.html +++ b/documentation/utf8.html @@ -8,7 +8,7 @@ - + @@ -52,14 +52,11 @@
Back
-
+
Documentation
UTF8
- About -
-
Standard Parameters
@@ -67,6 +64,7 @@
Specifications
+ UTF8
APIs
@@ -84,29 +82,23 @@

UTF8 Documentation

-
-
-

About

-
- -
-

- The UTF8 program is a tool for converting from a UTF-8 byte sequence to the Unicode code point. The byte sequence can also be referred to as the binary representation of the code even though the byte sequence is considered text. The term "byte sequence" here is used to refer to a sequence of bytes intended to represent something, which in this case is a Unicode character. The Unicode code point is the Unicode designation uniquely identifying that particular sequence. The Unicode code point is not specific to UTF-8 and persists across different encodings, such as UTF-16. -

-

- The idea behind the UTF8 program is to provide the answer to the question of what some special UTF-8 character is or to provide a way to create the UTF-8 character given the Unicode code point. -

-

- This tool is intended to be scriptable, should handle both piped data and files, and can convert entire files. -

-

- This tool can be used to validate a given byte sequence or can be used to get the character width of some byte sequence or code point. -

-

- This tool can be used to store binary data in a text-friendly format and then restore the binary data. -

-
-
+
+

+ The UTF8 program is a tool for converting from a UTF-8 byte sequence to the Unicode code point. The byte sequence can also be referred to as the binary representation of the code even though the byte sequence is considered text. The term "byte sequence" here is used to refer to a sequence of bytes intended to represent something, which in this case is a Unicode character. The Unicode code point is the Unicode designation uniquely identifying that particular sequence. The Unicode code point is not specific to UTF-8 and persists across different encodings, such as UTF-16. +

+

+ The idea behind the UTF8 program is to provide the answer to the question of what some special UTF-8 character is or to provide a way to create the UTF-8 character given the Unicode code point. +

+

+ This tool is intended to be scriptable, should handle both piped data and files, and can convert entire files. +

+

+ This tool can be used to validate a given byte sequence or can be used to get the character width of some byte sequence or code point. +

+

+ This tool can be used to store binary data in a text-friendly format and then restore the binary data. +

+
diff --git a/documentation/utf8/specifications.html b/documentation/utf8/specifications.html new file mode 100644 index 0000000..60f3568 --- /dev/null +++ b/documentation/utf8/specifications.html @@ -0,0 +1,95 @@ + + + + Documentation - UTF8 - Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

UTF8 Specifications

+
+ +
+

+ The FLL project provides several specifications. + The UTF8 does not use or provide any of these specifications. +

+
+
+
+
+ + diff --git a/documents/standards/fll/fss-0000.txt b/documents/standards/fll/fss-0000.txt index 252764f..ffe6259 100644 --- a/documents/standards/fll/fss-0000.txt +++ b/documents/standards/fll/fss-0000.txt @@ -4,32 +4,34 @@ # Featureless Settings Specification: 0000 - Basic: - Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as part of the object. - Whitespace separates an Object from the Content. + Each Object starts at the beginning of a line and white space to the left of the Object is not treated as part of the object. + White space separates an Object from the Content. An Object may be preceded by a newline, in which case means that the Object has no Content. - If only printing whitespace follows a valid Object, that Object is considered to have no Content. + If only printing white spaces or non-printable characters follow a valid Object, then that Object is considered to have no Content. Content exists on the same line as the Object. Content is represented as a single Content column terminated by a newline. - Content column consists of everything following the first non-whitespace character until the newline. - Content column includes trailing whitespace before newline is reached. - Content column does not include any of the leading whitespace. + Content column consists of everything following the first non-white space character until the newline. + Content column includes trailing white space before newline is reached. + Content column does not include any of the leading white space. No delimits are supported in the Content. Key\: - \s = whitespace, except newline. - \b = either whitespace or printable, except newline. - \q = non-whitespace or quoted whitespace with no whitespace outside of the quotes. - \n = newline. - * = zero or more occurrences. - + = one or more occurrences. + "\s" = White space, except newline. + "\b" = Either white space or printable, except newline. + "\q" = Non-white space or quoted white space with no white space outside of the quotes. + "\n" = Newline. + "*" = Zero or more occurrences. + "+" = One or more occurrences. Before Structure\: + "" Structure\: - \s*\q+\s+\b*\n + "\s*\q+\s+\b*\n" After Structure\: + "" Example\: # fss-0000 diff --git a/documents/standards/fll/fss-0001.txt b/documents/standards/fll/fss-0001.txt index e8086be..d753189 100644 --- a/documents/standards/fll/fss-0001.txt +++ b/documents/standards/fll/fss-0001.txt @@ -4,31 +4,33 @@ # Featureless Settings Specification: 0001 - Extended: - Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object. - Whitespace separates an Object from the Content. + Each Object starts at the beginning of a line and white space to the left of the Object is not treated as an object. + White space separates an Object from the Content. An Object may be followed by a newline, in which case means that the Object has no Content. - If only printing whitespace follows a valid Object, that Object is considered to have no Content. + If only printing white spaces or non-printable characters follow a valid Object, then that Object is considered to have no Content. Content exists on the same line as the Object. Content is represented as multiple Content columns. - Content columns are whitespace separated parts within the Content and terminated by a newline. + Content columns are white space separated parts within the Content and terminated by a newline. Any number of Content columns may exist in the Content until the newline is reached. Key\: - \s = whitespace, except newline. - \b = either whitespace or printable, except newline. - \q = non-whitespace or quoteded whitespace, no whitespace outside of quotes. - \n = newline. - * = 0 or more occurrences. - + = one or more occurrences. - ()* = grouping that repeats 0 or more times. + "\s" = White space, except newline. + "\b" = Either white space or printable, except newline. + "\q" = Non-white space or quoted white space, no white space outside of quotes. + "\n" = Newline. + "*" = Zero or more occurrences. + "+" = One or more occurrences. + "()*" = Grouping that repeats zero or more times. Before Structure\: + "" Structure\: - \s*\q+\s+(\s*\q+)*\s*\n + "\s*\q+\s+(\s*\q+)*\s*\n" After Structure\: + "" Example\: # fss-0001 diff --git a/documents/standards/fll/fss-0002.txt b/documents/standards/fll/fss-0002.txt index 37cbc31..191f173 100644 --- a/documents/standards/fll/fss-0002.txt +++ b/documents/standards/fll/fss-0002.txt @@ -2,13 +2,11 @@ # # license: open-standard-license-1.0 # -# Note: This file is in fss-0002 format and as a result the example below has to be escaped (can potentially be confusing when reading this raw). -# The "This Does\\\:" below is actually "This Does\:" when processed by fss-0002. Featureless Settings Specification: 0002 - Basic List: - Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object. - A colon followed by any whitespace until a newline terminates a valid Object. - Non-whitespace may not follow the colon of a valid Object. + Each Object starts at the beginning of a line and white space to the left of the Object is not treated as an object. + A colon ":" (U+003A) followed by any white space until a newline terminates a valid Object. + Non-white space printable characters may not follow the colon of a valid Object. Content is represented as a single Content column of every line following a valid object until the end of file (or string) or until the next valid Object is found. Any Content that could be interpreted as a valid Object must have the colon delimited. @@ -16,22 +14,24 @@ Featureless Settings Specification: 0002 - Basic List: There is no single-quote or double-quote delimitation in this specification. Only the colon that would result in a valid Object can be delimited. - Empty Objects are allowed, that is, the length of the object may be 0. + Empty Objects are allowed, that is, the length of the object may be zero. Key\: - \s = whitespace, except newline. - \o = any printable character, except unescaped ':'. - \l = any printable character or whitespace, except unescaped ':'. - \c = either whitespace or printable, including newline, that not interpretable as an Object. - \n = newline. - * = 0 or more occurrences. + "\s" = White space, except newline. + "\o" = Any printable character, except unescaped ":" (U+003A). + "\l" = Any printable character or white space, except unescaped ":" (U+003A). + "\c" = Either white space or printable, including newline, that not interpretable as an Object. + "\n" = Newline. + "*" = Zero or more occurrences. Before Structure\: + "" Structure\: - \s*\o\l*:\s*\n\c*\n* + "\s*\o\l*:\s*\n\c*\n*" After Structure\: + "" Example\: # fss-0002 @@ -42,7 +42,7 @@ Featureless Settings Specification: 0002 - Basic List: This Does\\\: Second\: Continues until EOS/EOF. - All whitespace, including newline (and leading whitespace) is "part of content." + All white space, including newline (and leading white space) is "part of content." # Valid comments are still ignored. Objects would be\: @@ -54,4 +54,4 @@ Featureless Settings Specification: 0002 - Basic List: This: does not need to be delimited. This Does\: 2.1) Continues until EOS/EOF. - All whitespace, including newline (and leading whitespace) is "part of content." + All white space, including newline (and leading white space) is "part of content." diff --git a/documents/standards/fll/fss-0003.txt b/documents/standards/fll/fss-0003.txt index 5d54726..73517fc 100644 --- a/documents/standards/fll/fss-0003.txt +++ b/documents/standards/fll/fss-0003.txt @@ -4,40 +4,42 @@ # Featureless Settings Specification: 0003 - Extended List: - Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object. - An open-brace ({) followed by any whitespace until a newline terminates a possible valid Object. - An Object is not considered fully valid until a valid close-brace (}) is found, designating the end of the Content. - Non-whitespace may not follow the open-brace of a valid Object. + Each Object starts at the beginning of a line and white space to the left of the Object is not treated as an object. + An open-brace "{" (U+007B) followed by any white space until a newline terminates a possible valid Object. + An Object is not considered fully valid until a valid close-brace "}" (U+007D) is found, designating the end of the Content. + Non-white space printable characters may not follow the open-brace of a valid Object. - Content is represented as a single Content column of every line following a valid object until the end of file (or string) or until a non-delimited close-brace (}). + Content is represented as a single Content column of every line following a valid object until the end of file (or string) or until a non-delimited close-brace "}". Any Content column that could be interpreted as an end of Content must be delimited if it should be part of the Content. - Whitespace may follow a valid close-brace but a terminating newline must be present to designate a valid end of Content. + White space may follow a valid close-brace but a terminating newline must be present to designate a valid end of Content. There is no single-quote or double-quote delimitation in this specification. Only the open-brace that would result in a valid Object or the close-brace that would terminate valid Content can be delimited. When inside potentially valid Content (which follows a valid Object) the open-brace cannot be delimited because this standard is not-recursive. When not inside any potentially valid Content (that is, there is no previous unclosed Object), then the Object may be delimited. - Likelwise, the close-brace may only be delimited if it is within any potentially valid Content. + Likewise, the close-brace may only be delimited if it is within any potentially valid Content. - Each delimit slash in a delimitable open-brace is treated as a potential delimit such that two slashes represents a single delimited slash ('\\{' would represent '\{'). - Only the first delimit slash in a delimitable close-brace is treated as a potential delimit ('\\\}' would represent '\\}'). + Each delimit slash in a delimitable open-brace is treated as a potential delimit such that two slashes represents a single delimited slash ("\\{" would represent "\{"). + Only the first delimit slash in a delimitable close-brace is treated as a potential delimit ("\\\}" would represent "\\}"). - Empty Objects are allowed, that is, the length of the object may be 0. + Empty Objects are allowed, that is, the length of the object may be zero. Key\: - \s = whitespace, except newline. - \o = any printable character, except unescaped '{'. - \l = any printable character or whitespace, except unescaped '}'. - \c = either whitespace or printable, including newline, that is not interpretable as an Object. - \n = newline. - * = 0 or more occurrences. + "\s" = White space, except newline. + "\o" = Any printable character, except unescaped "{" (U+007B). + "\l" = Any printable character or white space, except unescaped "}" (U+007D). + "\c" = Either white space or printable, including newline, that is not interpretable as an Object. + "\n" = Newline. + "*" = Zero or more occurrences. Before Structure\: + "" Structure\: - \s*\o\l*{\s*\n\c*\n\s*}\s*\n + "\s*\o\l*{\s*\n\c*\n\s*}\s*\n" After Structure\: + "" Example\: # fss-0003 @@ -50,7 +52,7 @@ Featureless Settings Specification: 0003 - Extended List: Second { Continues until EOS/EOF. - All whitespace, including newline (and leading whitespace) is "part of content." + All white space, including newline (and leading white space) is "part of content." # Valid comments are still ignored. } @@ -63,4 +65,4 @@ Featureless Settings Specification: 0003 - Extended List: This: does not need to be delimited. } 2.1) Continues until EOS/EOF. - All whitespace, including newline (and leading whitespace) is "part of content." + All white space, including newline (and leading white space) is "part of content." diff --git a/documents/standards/fll/fss-0004.txt b/documents/standards/fll/fss-0004.txt index edc42fa..905b6b3 100644 --- a/documents/standards/fll/fss-0004.txt +++ b/documents/standards/fll/fss-0004.txt @@ -4,9 +4,9 @@ # Featureless Settings Specification: 0004 - Very Basic List: - This is a fss-0002 Basic List whose Content is then processed as fss-0000 Basic. + This is a "FSS-0002 (Basic List)" whose Content is then processed as "FSS-0000 (Basic)". - All Basic List (fss-0002) escapes are applied before any Basic (fss-0000) is identified. + All "FSS-0002 (Basic List)" escapes are applied before any "FSS-0000 (Basic)" is identified. See the fss-0000.txt and fss-0002.txt specification files for details on the syntax rules. @@ -19,7 +19,7 @@ Featureless Settings Specification: 0004 - Very Basic List: This Does\\\: Second\: Continues until EOS/EOF. - All whitespace, including newline (and leading whitespace) is "part of content." + All white space, including newline (and leading white space) is "part of content." # Valid comments are still ignored. Outer Objects would be\: @@ -40,4 +40,4 @@ Featureless Settings Specification: 0004 - Very Basic List: 1.3.1) Does\: 2.1.1) until EOS/EOF. - 2.2.1) whitespace, including newline (and leading whitespace) is "part of content." + 2.2.1) white space, including newline (and leading white space) is "part of content." diff --git a/documents/standards/fll/fss-0005.txt b/documents/standards/fll/fss-0005.txt index cb4ec32..2cc6caf 100644 --- a/documents/standards/fll/fss-0005.txt +++ b/documents/standards/fll/fss-0005.txt @@ -4,9 +4,9 @@ # Featureless Settings Specification: 0005 - Somewhat Basic List: - This is a fss-0002 Basic List whose Content is then processed as fss-0001 Extended. + This is a code"fss-0002 (Basic List)" whose Content is then processed as "FSS-0001 (Extended)". - All Basic List (fss-0002) escapes are applied before any Extended (fss-0001) is identified. + All "FSS-0002 (Basic List)" escapes are applied before any "FSS-0001 (Extended)" is identified. See the fss-0001.txt and fss-0002.txt specification files for details on the syntax rules. @@ -19,7 +19,7 @@ Featureless Settings Specification: 0005 - Somewhat Basic List: This Does\\\: Second\: Continues until EOS/EOF. - All whitespace, including newline (and leading whitespace) is "part of content." + All white space, including newline (and leading white space) is "part of content." # Valid comments are still ignored. Outer Objects would be\: @@ -53,11 +53,11 @@ Featureless Settings Specification: 0005 - Somewhat Basic List: 2.1.1) until 2.1.2) EOS/EOF. - 2.2.1) whitespace, + 2.2.1) white space, 2.2.2) including 2.2.3) newline 2.2.4) (and 2.2.5) leading - 2.2.6) whitespace) + 2.2.6) white space) 2.2.7) is 2.2.8) part of content. diff --git a/documents/standards/fll/fss-0006.txt b/documents/standards/fll/fss-0006.txt index 1cc6e18..f4ac239 100644 --- a/documents/standards/fll/fss-0006.txt +++ b/documents/standards/fll/fss-0006.txt @@ -4,9 +4,9 @@ # Featureless Settings Specification: 0006 - Somewhat Extended List: - This is a fss-0003 Extended List whose Content is then processed as fss-0000 Basic. + This is a "FSS-0003 (Extended List)" whose Content is then processed as "FSS-0000 (Basic)". - All Extended List (fss-0003) escapes are applied before any Basic (fss-0000) is identified. + All "FSS-0003 (Extended List)" escapes are applied before any "FSS-0000 (Basic)" is identified. See the fss-0000.txt and fss-0003.txt specification files for details on the syntax rules. @@ -21,7 +21,7 @@ Featureless Settings Specification: 0006 - Somewhat Extended List: Second { Continues until EOS/EOF. - All whitespace, including newline (and leading whitespace) is "part of content." + All white space, including newline (and leading white space) is "part of content." # Valid comments are still ignored. } @@ -43,4 +43,4 @@ Featureless Settings Specification: 0006 - Somewhat Extended List: 1.3.1) 2.1.1) until EOS/EOF. - 2.2.1) whitespace, including newline (and leading whitespace) is "part of content." + 2.2.1) white space, including newline (and leading white space) is "part of content." diff --git a/documents/standards/fll/fss-0007.txt b/documents/standards/fll/fss-0007.txt index 3c377f5..29ba17d 100644 --- a/documents/standards/fll/fss-0007.txt +++ b/documents/standards/fll/fss-0007.txt @@ -4,9 +4,9 @@ # Featureless Settings Specification: 0007 - Very Extended List: - This is a fss-0003 Extended List whose Content is then processed as fss-0001 Extended. + This is a "FSS-0003 (Extended List)" whose Content is then processed as "FSS-0001 (Extended)". - All Extended List (fss-0003) escapes are applied before any Extended (fss-0001) is identified. + All "FSS-0003 (Extended List)" escapes are applied before any "FSS-0001 (Extended)" is identified. See the fss-0001.txt and fss-0003.txt specification files for details on the syntax rules. @@ -21,7 +21,7 @@ Featureless Settings Specification: 0007 - Very Extended List: Second { Continues until EOS/EOF. - All whitespace, including newline (and leading whitespace) is "part of content." + All white space, including newline (and leading white space) is "part of content." # Valid comments are still ignored. } @@ -56,11 +56,11 @@ Featureless Settings Specification: 0007 - Very Extended List: 2.1.1) until 2.1.2) EOS/EOF. - 2.2.1) whitespace, + 2.2.1) white space, 2.2.2) including 2.2.3) newline 2.2.4) (and 2.2.5) leading - 2.2.6) whitespace) + 2.2.6) white space) 2.2.7) is 2.2.8) part of content. diff --git a/documents/standards/fll/fss-0008.txt b/documents/standards/fll/fss-0008.txt index b020921..e620a8c 100644 --- a/documents/standards/fll/fss-0008.txt +++ b/documents/standards/fll/fss-0008.txt @@ -4,7 +4,7 @@ # Featureless Settings Specification: 0008 - Embedded List: - This is a fss-0003 Extended List whose Content is then recursively processed as fss-0003 Extended List. + This is a "FSS-0003 (Extended List)" whose Content is then recursively processed as "FSS-0003 (Extended List)". See the fss-0003.txt specification file for details on the syntax rules. diff --git a/documents/standards/fll/fss-0009.txt b/documents/standards/fll/fss-0009.txt index aa322bc..9ebe04f 100644 --- a/documents/standards/fll/fss-0009.txt +++ b/documents/standards/fll/fss-0009.txt @@ -4,34 +4,36 @@ # Featureless Settings Specification: 0009 - Reverse Mapping: - This is based off of fss-0000 Basic, except the Object is at the end of the line. + This is based off of "FSS-0000 (Basic)", except the Object is at the end of the line. - Each Object starts at the end of a line and whitespace to the left of the Object is not treated as part of the object. - Whitespace separates an Object from the Content. + Each Object starts at the end of a line and white space to the left of the Object is not treated as part of the object. + White space separates an Object from the Content. An Object may be preceded by a newline, in which case means that the Object has no Content. - If only printing whitespace precedes a valid Object, that Object is considered to have no Content. + If only printing white spaces or non-printable characters precedes a valid Object, then that Object is considered to have no Content. Content exists on the same line as the Object. Content is represented as a single Content column that begins at a newline. - Content column consists of everything following the first non-whitespace character at the start of the line until the Object is reached. - Content column includes trailing whitespace before newline is reached. - Content column does not include any of the whitespace between the last non-whitespace character and the start of the Object. + Content column consists of everything following the first non-white space character at the start of the line until the Object is reached. + Content column includes trailing white space before newline is reached. + Content column does not include any of the white space between the last non-white space character and the start of the Object. No delimits are supported in the Content. Key\: - \s = whitespace, except newline. - \b = either whitespace or printable, except newline. - \q = non-whitespace or quoted whitespace with no whitespace outside of the quotes. - \n = newline. - * = zero or more occurrences. - + = one or more occurrences. + "\s" = White space, except newline. + "\b" = Either white space or printable, except newline. + "\q" = Non-white space or quoted white space with no white space outside of the quotes. + "\n" = Newline. + "*" = Zero or more occurrences. + "+" = One or more occurrences. Before Structure\: + "" Structure\: - \s*\b*\s+\q+\s*\n + "\s*\b*\s+\q+\s*\n" After Structure\: + "" Example\: # fss-0009 diff --git a/documents/standards/fll/fss-000a.txt b/documents/standards/fll/fss-000a.txt index e023ac5..9da12c6 100644 --- a/documents/standards/fll/fss-000a.txt +++ b/documents/standards/fll/fss-000a.txt @@ -4,33 +4,35 @@ # Featureless Settings Specification: 000A - Extended Reverse Mapping: - This is based off of fss-0001 Extended, except the Object is at the end of the line. + This is based off of "FSS-0001 (Extended)", except the Object is at the end of the line. - Each Object starts at the end of a line and whitespace to the left of the Object is not treated as an object. - Whitespace separates an Object from the Content. + Each Object starts at the end of a line and white space to the left of the Object is not treated as an object. + White space separates an Object from the Content. An Object may be followed by a newline, in which case means that the Object has no Content. - If only printing whitespace follows a valid Object, that Object is considered to have no Content. + If only printing white spaces or non-printable characters follow a valid Object, then that Object is considered to have no Content. Content exists on the same line as the Object. Content is represented as multiple Content columns. - Content columns are whitespace separated parts within the Content is terminated by the start of the Object. + Content columns are white space separated parts within the Content is terminated by the start of the Object. Any number of Content columns may exist in the Content until the Object is reached. Key\: - \s = whitespace, except newline. - \b = either whitespace or printable, except newline. - \q = non-whitespace or quoteded whitespace, no whitespace outside of quotes. - \n = newline. - * = 0 or more occurrences. - + = one or more occurrences. - ()* = grouping that repeats 0 or more times. + "\s" = White space, except newline. + "\b" = Either white space or printable, except newline. + "\q" = Non-white space or quoted white space, no white space outside of quotes. + "\n" = Newline. + "*" = Zero or more occurrences. + "+" = One or more occurrences. + "()*" = Grouping that repeats zero or more times. Before Structure\: + "" Structure\: - \s*(\s*\q+)*\s+\q+\s*\n + "\s*(\s*\q+)*\s+\q+\s*\n" After Structure\: + "" Example\: # fss-000a diff --git a/documents/standards/fll/fss-000b.txt b/documents/standards/fll/fss-000b.txt index 0be7a62..37d00ec 100644 --- a/documents/standards/fll/fss-000b.txt +++ b/documents/standards/fll/fss-000b.txt @@ -4,7 +4,7 @@ # Featureless Settings Specification: 000B - Simple List: - This might be similar to fss-0008 - Embedded List, except it is an fss-0003 Extended List with a (non-recursive) fss-0002 Basic List inside the Content. + This is similar to "FSS-0008 (Embedded List)", except that it is an "FSS-0003 (Extended List)" with a (non-recursive) "FSS-0002 (Basic List)" inside the Content. See the fss-0002.txt and fss-0003.txt specification files for details on the syntax rules. diff --git a/documents/standards/fll/fss-000c.txt b/documents/standards/fll/fss-000c.txt index bff3a0d..736cc52 100644 --- a/documents/standards/fll/fss-000c.txt +++ b/documents/standards/fll/fss-000c.txt @@ -4,10 +4,10 @@ # Featureless Settings Specification: 000C - IKI Text: - The IKI specifications are separate specifications from the FSS specification. + The IKI specifications are separate specifications from the FSS. This is simply a more formal way to designate that this format utilizes IKI syntax. - The IKI syntax may be used in any FSS specification. + The IKI syntax may be used in any FSS. The IKI format may be added to the. See the iki.txt specification for details on the IKI specifications. @@ -15,9 +15,9 @@ Featureless Settings Specification: 000C - IKI Text: Example\: # fss-000c iki-0000 - This is a emphasis:"formal example" utilizing the FSS headers. + This is a formal example utilizing the FSS headers. Example\: # iki-0000 - This is a emphasis:"informal example" utilizing the IKI headers. + This is a informal example utilizing the IKI headers. diff --git a/documents/standards/fll/fss-000d.txt b/documents/standards/fll/fss-000d.txt index c7cb0d1..f4e37aa 100644 --- a/documents/standards/fll/fss-000d.txt +++ b/documents/standards/fll/fss-000d.txt @@ -4,24 +4,24 @@ # Featureless Settings Specification: 000D - Basic Rule: - This is a special case that follows fss-0002 (Basic List), and different FSS formats inside this Basic List. - This Basic List is considered the "Outer List" and the Content of this Outer List is considered the "Inner Content". + This is a special case that follows "FSS-0002 (Basic List)", and different FSS formats inside this "FSS-0002 (Basic List)". + This "FSS-0002 (Basic List)" is considered the "Outer List" and the Content of this Outer List is considered the "Inner Content". - The Inner Content may be any of the following FSS formats: fss-0000 (Basic), fss-0001 (Extended), and fss-0003 (Extended List). + The Inner Content may be any of the following FSS formats: "FSS-0000 (Basic)", "FSS-0001 (Extended)", and "FSS-0003 (Extended List)". The way in which each format is determined is first to see if the Inner Content Object would be a valid Extended List Object. - If the Inner Content Object is not a valid Extended List Object, then check to see if it is an Basic/Extended Object. + If the Inner Content Object is not a valid "FSS-0003 (Extended List)" Object, then check to see if it is an "FSS-0000 (Basic)" or "FSS-0001 (Extended)" Object. - The FSS Basic and FSS Extended Objects have the same format for Object names but the FSS Extended List Object is slightly different. - Anything that would match an FSS Extended List Object must therefore be an FSS Extended List Object. + The "FSS-0000 (Basic)" and "FSS-0001 (Extended)" Objects have the same format for Object names but the "FSS-0003 (Extended List)" Object is slightly different. + Anything that would match an "FSS-0003 (Extended List)" Object must therefore be an "FSS-0003 (Extended List)" Object. - This supports the use of iki-0000 (Unrestricted) but only within the Content of the outermost Basic List. + This supports the use of "iki-0000 (Unrestricted)" but only within the Content of the outermost "FSS-0002 (Basic List)". That is to say, the IKI is only processed once. Additional restrictions on the use of IKI syntax is allowed if explicitly defined in the implementing specification. - This additional restriction may also include using a more restrictive IKI syntax, such as "iki-0001 (Basic IKI)". + This additional restriction may also include using a more restrictive IKI syntax, such as "iki-0001 (Basic)". Anything implementing this specification may impose its own restrictions on when to determine if the Inner Content is what FSS format, based on Object names. - See the fss-0000.txt, fss-0001.txt and fss-0003.txt specification files for details on the syntax rules. + See the fss-0000.txt, fss-0001.txt, and fss-0003.txt specification files for details on the syntax rules. Example\: # fss-000d diff --git a/documents/standards/fll/fss-000e.txt b/documents/standards/fll/fss-000e.txt index 1309da9..3ee723f 100644 --- a/documents/standards/fll/fss-000e.txt +++ b/documents/standards/fll/fss-000e.txt @@ -2,40 +2,39 @@ # # license: open-standard-license-1.0 # -# -# Note: This file is in fss-0002 format and as a result the example below has to be escaped (can potentially be confusing when reading this raw). -# The "header\:" in the example below is actually "header:" when processed by fss-0002. Featureless Settings Specification: 000e - Payload: - This is a fss-0002 Basic List with two required objects\: - 1) "header". - 2) "payload". + This is a "FSS-0002 (Basic List)" with two required objects\: + 1) header. + 2) payload. - The header's Content is of type fss-0001 Extended. - The payload's Content is of any type including raw binary data. + The header\: + - The header's Content is of type "FSS-0001 (Extended)". + - The header is recommended to have the Objects length, status, part, and total. + - The recommended length represents the size of the payload. + - The recommended part represents a single part of a set of packets for when the data being transmitted is split across multiple payloads. + - The recommended total represents the total number of parts representing a complete data transmitted across multiple payloads. + - The recommended status represents status codes (such as success or failure) and multiple. + - The Content for the recommended length and status are positive whole numbers (including zero) that may be in binary, octal, decimal, duodecimal, or hexidecimal numerical format. - The payload is required to be the last list Object in the file. - The payload is recommended to have its size designated in some manner in the "header". - The designated size is recommended to use the fss-0001 Object "length". - The fss-0001 Content "part" is suggested to be used for fss-0001 Object "length" to represent a part of a set of packets intended to represent a single object spread across multiple payloads. - The fss-0001 Object "total" with the Content being a whole positive number is suggested to be used to represent the total number of packets that represent a whole. - The fss-0001 Object "part" with the Content being a whole positive number is suggested to be used to represent the number identifying which part of the whole it is. - The payload may contain anything, including NULL characters. - The payload is terminated by the EOF (end of file) character or when a some designated length is reached. - The length used to designate the payload size does not necessarily have to be defined in the 'header". - That is to say, if the payload is expected to be of some pre-defined or static length then a length does even if that length is not provided in the "header". - Nothing in the payload may be considered a valid list Object and therefore there will be no escaping allowed (No further fss-0002 Basic List Objects are allowed at this point). - Comments are not considered comments inside the payload and are instead considered part of the payload, as-is. - The payload may be empty (length may be zero), but the list Object "payload" must still exist. + The payload\: + - The payload's Content may contain anything, including raw binary data. + - The payload is required to be the last list Object in the file. + - The payload is recommended to have its size designated in some manner in the header (such as with the recommended length). + - The payload is terminated by the EOF character or by the recommended length header. + - The payload may be empty (length may be zero), but the list Object payload must still exist. + - Nothing in the payload may be considered a valid list Object by the outer "FSS-0002 (Basic List)" and therefore escaping is unnecessary (No further processing by the outer "FSS-0002 (Basic List)" is allowed at this point). + - Comments in the payload are not considered comments and are instead considered part of the payload, as-is. + - Essentially, the payload should be treated as binary data embedded in a text file. - The length and status may be in binary, octal, decimal, duodecimal, or hexidecimal numerical format. - The status may alternatively be represented as the status name string. - What the status code represents is application specific (or specific to a sub-standard) but may often be used to represent FLL status codes. - The status, when representing an FLL status code as a number, may contain error and warning bit. - The status, when representing an FLL status code as a number, the status number is binary sensitive and may not be portable across binaries or systems. - For FLL status codes, consider using status as a name string to ensure cross-system or cross-binary compatibility. + The recommended length header Object used to designate the payload size does not necessarily have to be defined in the header. + That is to say, if the payload is expected to be of some pre-defined or static length then a length does not need to be provided in the header. - Other than the reserved list Objects "header" and "payload" any other valid Object may be specified. + The recommended status header Object may be a string, such as "F_none", or a positive whole number. + What the status code represents is application specific (or specific to a sub-standard) but may often be used to represent FLL status code. + - The FLL status code is a 16-bit digit whose first two high-order bits represent error and warning ( representing signal). + - The FLL status code as a number is binary sensitive and may not be portable across binaries or systems. + - For best portability, consider using status as a name string to ensure cross-system or cross-binary compatibility. Example\: # fss-000e diff --git a/documents/standards/fll/fss-000f.txt b/documents/standards/fll/fss-000f.txt index 6cafcb7..cf2d4e6 100644 --- a/documents/standards/fll/fss-000f.txt +++ b/documents/standards/fll/fss-000f.txt @@ -4,7 +4,7 @@ # Featureless Settings Specification: 000f - Simple Packet: - This is a network packet format that contains FSS-000E (Payload) within it. + This is a network packet format that contains "FSS-000e (Payload)" within it. The Simple Packet structure is described in blocks, of which are structured in bytes. @@ -15,12 +15,12 @@ Featureless Settings Specification: 000f - Simple Packet: The Control Block is the first block in the packet and is considered endianless. There exists only a single byte within the Control Block. - Regardless of the endianness of the packet, the leftmost bit is always the "string" or "binary" bit. + Regardless of the endianness of the packet, the leftmost bit is always the string or binary bit. The second bit following that bit represents the endianness bit. - The "string" or "binary" bit, a value of 0 designates that the packet is in string format and a value of 1 designates that the packet is in binary format. + The string or binary bit, a value of 0 designates that the packet is in string format and a value of 1 designates that the packet is in binary format. While the packet might be considered to be in string format, it is technically always in binary format due to the Control Block and Size Block. - This means that the bit designating the packet as a "string" packet or a "binary" packet is referring to whether or not the Payload Block is in "string" format or is in "binary" format. + This means that the bit designating the packet as a string packet or a binary packet is referring to whether or not the Payload Block is in string format or is in binary format. The endianness bit designates whether or not the packet is in big endian or little endian format. A bit value of 0 designates that this packet is in little endian and a value of 1 designates that this packet is in big endian format. @@ -36,10 +36,12 @@ Featureless Settings Specification: 000f - Simple Packet: The size represents number of bytes in the file. The Control Block is 1 byte long and the Size Block is 4 bytes long and so the maximum available size is (2^32)-6. - The Payload Block is not defined by this standard of that that it exists and should be in FSS-000E (Payload) format. - The FSS-000E (Payload) may be represented in either string format or binary format. - The FSS-000E (Payload) may contain multiple "header"s but may only contain a single "payload". - With this in mind, it is recommended that only a single "header" be supported in the Payload Block. + The Payload Block is not defined by this standard of that that it exists and should be in "FSS-000e (Payload)" format. + The "FSS-000e (Payload)" may be represented in either string format or binary format. + The "FSS-000e (Payload)" may contain multiple header(s) but may only contain a single payload. + With this in mind, it is recommended that only a single header be supported in the Payload Block. + + See the fss-000e.txt specification file for details on the syntax rules for the Payload Block. Example Packet Structure\: [ Control Block ] [ Size Block ] [ Payload Block ] diff --git a/documents/standards/fll/fss.txt b/documents/standards/fll/fss.txt index 06bf0f9..de398f3 100644 --- a/documents/standards/fll/fss.txt +++ b/documents/standards/fll/fss.txt @@ -4,40 +4,46 @@ # Featureless Settings Specifications: - A Keep It Simple Stupid specifications for configuration/settings files. + The Featureless Settings Specifications describe a set of standards designed around the age-old design principle referred to as Keep It Simple Stupid, aka KISS. The FSS are primarily intended for settings files but are extensible enough to be used beyond that. - This specification defines the following\: + The FSS defines the following\: - Will consist of numerous different kinds of specification files, depending on the type of information stored. - - As with the practice of "#!/bin/bash", the setting files SHOULD have the following: "# fss-????" format, such as "# fss-0001". + - As with the practice of "#!/bin/bash", the setting files should have the following: "# fss-????" format, such as "# fss-0001". - Multiple sub-standards may be appended to the FSS header, using the same format structure, such as supporting IKI: "# fss-0000 iki-0000" or HTML5: "# fss-0000 html-0005". - - With the ? representing the (hexadecimal/base-16) number that represents the particular specification structure. - - All settings specifications SHOULD avoid any form of noise, relative to the data being stored. + - With the "?" representing the (hexadecimal/base-16) number that represents the particular specification structure. + - All settings specifications should avoid any form of noise, relative to the data being stored. - XML would be considered anti-KISS due to the extreme level of noise generated by the XML language (not easy to read). - The settings files are setup so that they should (reasonably) produce easy readability on both the console and in a GUI. + - The specifications should strive for completeness (see the completeness theorem). - The most basic form of FSS specifications consist of two main parts: an "Object" and the "Content". - - Object: Considered the name or identifier of some particular data; Objects do not need an associated Content. - - Content: The data associated with a given Object; all Content MUST have an associated Object. + The most basic form of FSS consists of two main parts: an Object and the Content. + - Object: Considered the name or identifier of some property or data; Objects do not require an associated Content. + - Content: The data associated with a given Object; all Content must have an associated Object. Objects and Contents can include any characters allowed by the specifications. The specification may choose how a given Object or Content are represented and parsed. - For example, in fss-0000 (Basic), Content is treated as a single item whereas in fss-0001 (Extended), Content is broken apart in multiple sub parts. + For example, in "FSS-0000 (Basic)", Content is treated as a single item whereas in "FSS-0001 (Extended)", Content is broken apart in multiple sub-parts. Contents may be broken up into zero or more discrete sets of Content. Each of these discrete sets of Content are referred to as a column. - These columns do not need to be setup in a column structure, the word "column" is simply used as a grouping terminology. + These columns do not need to be setup in a column structure, the word column is simply used as a grouping terminology. While a Content refers to the entire set, a column (more specifically, a Content column) refers to the individual discrete sets within the Content. - For example, in fss-000 (Basic) the entire Content may be further represented as a single column. - For example, in fss-001 (Extended) the entire Content may be further represented as multiple columns. + For example, in "FSS-000 (Basic)" the entire Content may be further represented as a single column. + For example, in "FSS-001 (Extended)" the entire Content may be further represented as multiple columns. In all cases, specifications that separate Objects from Contents using white space, the first white space separating the Object and Content must not be considered part of the Object nor part of the Content. All spaces after the first separating white space is generally ignored until the first non white space character is found, unless otherwise specified. - Unless otherwise specified, all specifications are newline sensitive ('\n' only). - Newline characters are only '\n' and are never anything else ('\r' is not considered newline in any manner). - Whitespaces characters that are printable, such as tabs and spaces, must be considered the same type for the purposes of parsing. - Non-printing white spaces characters (zero-width characters) are ignored, are treated as placeholders for processing, or are considered part of the appropriate character if they are Unicode combining characters (this includes zero-width punctutations characters and similar). - In terms of processing, it is recommended that the NULL character is not considered the end of a string, but this is only a suggestion. + Unless otherwise specified, all specifications are newline sensitive ("\n" only). + Newline characters are only "\n" and are never anything else ("\r" is not considered newline in any manner). + These specifications refer to characters that have printable representation as printable. + These specifications refer to characters that have no printable representation as non-printable. + White spaces characters that are printable, such as tabs and spaces, must be considered the same type for the purposes of parsing. + Non-printing white spaces characters (zero-width characters) are ignored, are treated as placeholders for processing with the exception of combining characters. + White spaces that use combining characters result in printable characters and the resulting combination is treated as not white space. + Zero-width characters that use combining characters are treated as non-printing characters and are skipped. + In terms of processing, it is recommended that the "NULL" character is not considered the end of a string, but this is only a suggestion. + Any specification may chose to limit, restrict, or otherwise prohibit special Unicode characters such as combining characters or zero-width characters. Unless otherwise specified, newlines designate the potential start (or end) of an Object or Content. @@ -47,8 +53,8 @@ Featureless Settings Specifications: Unless otherwise specified, white space immediately both before (and after, outside of the terminating quote) an Object is not considered part of the Object. This simplifies identifying the object, use quoted Objects to support white space before/after an object for styling purposes. - Unless otherwise specified, quotes may only be either a single quote (') or a double quote (") and only a backslash '\' may be used as a delimiter. - For example, fss-0000 (Basic)\: + Unless otherwise specified, quotes may only be either a single quote "'" or a double quote """ and only a backslash "\" may be used as a delimiter. + For example, "FSS-0000 (Basic)"\: \"Object 1" has content starting at the '1', with an Object named '"Object'. \\"Object 1" has content starting at the '1', with an Object named '\"Object'. "Object 1\" is an unterminated object due to the escaped closing quote. @@ -56,7 +62,7 @@ Featureless Settings Specifications: Unless otherwise specified, character/data delimits are performed only when required and not unilaterally. In the case of Objects, delimits would only apply when that Object could be potentially identified as an Object. - For example, fss-0001 (Extended) needs quotes to group parts that include spaces, if there is no initial quote, then a quote following the data MUST NOT be delimited. + For example, "FSS-0001 (Extended)" needs quotes to group parts that include spaces, if there is no initial quote, then a quote following the data must not be delimited. Such as these following three lines\: "Object 1" "This is a single quoted Content." \"Additional unquoted Content." Object_2 This is multiple" Contents and the trailing quote does not need to be delimited. @@ -101,35 +107,34 @@ Featureless Settings Specifications: Those encodings must only support the appropriate characters required by a given standard for differentiating Objects, Contents, and delimits. All specifications do assume ASCII and Unicode support. - Unless otherwise specified, comments are designated by the pound symbol '#' but only if only white space is to the left of the pound or the pound '#' is at the start of the line. + Unless otherwise specified, comments are designated by the pound symbol "#" but only if only white space is to the left of the pound or the pound "#" is at the start of the line. There is no support for inline comments. - Unless otherwise specified, the start comment may be delimited by '\' in the same manner as Objects and Contents are. - This delimit only applies to the start of a comment (the pound '#' character) as there is no terminating character for a comment (other than a newline '\n'). + Unless otherwise specified, the start comment may be delimited by "" in the same manner as Objects and Contents are. + This delimit only applies to the start of a comment (the pound character:"#" character) as there is no terminating character for a comment (other than a newline "\n"). A line containing a valid comment is in its entirety ignored. - This means that if there is white space before the designation symbol (the pound '#' character) then that white space is ignored. + This means that if there is white space before the designation symbol (the pound "#" character) then that white space is ignored. - Unless otherwise specified, all designation characters MUST represent ASCII codes. - With designation characters being any character code used to designate how to identify an Object or Content (such as a colon ':' at the end of a basic list). + Unless otherwise specified, all designation characters must represent ASCII codes. + With designation characters being any character code used to designate how to identify an Object or Content (such as a colon ":" at the end of a basic list). This keeps the processing and logic simple and safe, for both UTF-8 and ASCII. - Whitespace used for designation characters MUST include support for UTF-8 white space characters, unless otherwise specified. + White space used for designation characters must include support for UTF-8 white space characters, unless otherwise specified. However, these white space used as a designation character, must be printing white space that are not combining white space characters. - Any visible/graph character that is considered a white space (such as U+1680 ' ') is not to be considered a white space, unless otherwise specified. + Any visible/graph character that is considered a white space (such as U+1680 " ") is not to be considered a white space, unless otherwise specified. When used for syntax matching purposes, zero-width Unicode characters are only to be considered zero-width unless otherwise specified. - For example, the "invisible plus" character (U+2064) is not to be considered as a plus. + For example, the invisible plus character (U+2064) is not to be considered as a plus. The UTF-8 BOM is not allowed as a Byte Order Mark; instead, it must always be treated as the character represented by its code (unless explicitly allowed to represent a BOM by a standard). - The only Unicode dash-like characters allowed as a "dash" are those intended to connect, such as the Unicode hyphens (U+2010 and U+2011) (unless otherwise specified). + The only Unicode dash-like characters allowed as a dash are those intended to connect, such as the Unicode hyphens (U+2010 and U+2011) (unless otherwise specified). - In any specification where security is intended, if there exists a Unicode character that matches an ASCII character, that Unicode character MAY be prohibited by that standard in favor of the ASCII equivalent. + In any specification where security is intended, if there exists a Unicode character that matches an ASCII character, that Unicode character may be prohibited by that standard in favor of the ASCII equivalent. One such example is in the case of a URL, where the name could be used to trick a person (http://this-site.com/ vs http://this‐site.com/). This (potential insecure behavior) is allowed in general because a well written program would be able to detect and communicate the possible misunderstanding and thereby avoid mistakes without imposing any character restrictions. - This is a common behavior for security reasons, each character used for any special purposes must be visibly distinct, with white space and non-printing characters as the exception to the words "visibly distinct". + This is a common behavior for security reasons, each character used for any special purposes must be visibly distinct, with white space and non-printing characters as the exception to the words visibly distinct. - The follow specifications are defined in this project. - Each of these specifications has a common name associated with the specification number. + The following are core specifications (each with a common name associated with the specification number)\: - fss-0000: Basic - fss-0001: Extended - fss-0002: Basic List @@ -142,7 +147,7 @@ Featureless Settings Specifications: - fss-0009: Reverse Mapping - fss-000a: Extended Reverse Mapping - fss-000b: Simple List - - fss-000c: Iki Text + - fss-000c: IKI Text - fss-000d: Basic Rule - fss-000e: Payload - fss-000f: Simple Packet diff --git a/documents/standards/fll/iki-0001.txt b/documents/standards/fll/iki-0001.txt index 08a35cf..3387716 100644 --- a/documents/standards/fll/iki-0001.txt +++ b/documents/standards/fll/iki-0001.txt @@ -7,14 +7,14 @@ IKI Specification: 0001 - Basic: This specification provides a small set of vocabulary names meant to be associated with common uses, such as e-mail addresses and URLs. Vocabulary\: - - address: any mailing address, except for e-mail and URI. - - code: all text contained within represent code and should be presented as such. - - email: any valid e-mail address. - - phone: any valid phone number. - - quote: all text within represents some quote. - - uri: any valid URI (allows URL and URN). - - url: any valid URL. - - urn: any valid URN. - - var: all text contained within represents some sort of variable. + - address: Any mailing address, except for e-mail and URI. + - code: All text contained within represent code and should be presented as such. + - email: Any valid e-mail address. + - phone: Any valid phone number. + - quote: All text within represents some quote. + - uri: Any valid URI (allows URL and URN). + - url: Any valid URL. + - urn: Any valid URN. + - var: All text contained within represents some sort of variable. See the iki.txt specification file for details on the syntax rules. diff --git a/documents/standards/fll/iki-0002.txt b/documents/standards/fll/iki-0002.txt index b67d84d..81fd4b6 100644 --- a/documents/standards/fll/iki-0002.txt +++ b/documents/standards/fll/iki-0002.txt @@ -10,12 +10,12 @@ IKI Specification: 0002 - Simple Script: This vocabulary may be further extended but must at least support the taxonomy defined here. Flexibility on interpretation is intended so that the context can be more fine-tuned and customized. - The taxonomy for the "context", "define", and "parameter" are intentionally not defined here and left open. + The taxonomy for the context, define, and parameter are intentionally not defined here and left open. One utilizing this should document the taxonomy for each of these as desired. Vocabulary\: - - context: intended to be used for printing (or tagging) context codes before and after text, such as with color context. - - define: intended to be used for global properties, much like a C/C++ #define. - - parameter: intended to be used for parameters or variables. + - context: Intended to be used for printing (or tagging) context codes before and after text, such as with color context. + - define: Intended to be used for global properties, much like a C/C++ "#define". + - parameter: Intended to be used for parameters or variables. See the iki.txt specification file for details on the syntax rules. diff --git a/documents/standards/fll/iki.txt b/documents/standards/fll/iki.txt index 7c84ab3..e2d5f61 100644 --- a/documents/standards/fll/iki.txt +++ b/documents/standards/fll/iki.txt @@ -7,42 +7,43 @@ IKI Specifications: IKI is a minimally structured WIKI-like syntax meant to be simpler than WIKI syntax. The IKI syntax provides a vocabulary name (with specific context associated with it) followed by quoted code that is associated with the given vocabulary name. - The vocabulary represents a list of allowed object names that may also have specific contextual meaning defined by a given IKI specification. - The variable name is considered the "Object". - The variable variable is considered the "Content". + The vocabulary represents a list of allowed variable names that may also have specific contextual meaning defined by a given IKI specification. + The variable name is considered the Object. + The variable value is considered the Content. - The IKI format will use iki-0000 to represent an IKI with no explicitly defined vocabulary. - Whereas iki-0001 and beyond represent a specific IKI vocabulary. + The IKI format will use "iki-0000" to represent an IKI with no explicitly defined vocabulary. + Whereas "iki-0001" and beyond represent a specific IKI vocabulary. A potential IKI variable name starts on word (or "_", "-", "+") characters. - Whitespace and non-word (and non "_", "-", "+") character punctuations may not exist as part of the variable name. + White space and non-word (and non "_", "-", "+") character punctuations may not exist as part of the variable name. The only Unicode dash-like characters allowed as a "dash" are those intended to connect, such as the Unicode hyphens (U+2010 and U+2011). - Any valid IKI data may be escaped to make it treated as non-IKI data by prepending a backslash "\" before the colon ":" that is before the opening quote (single or double). + Any potential IKI data must be escaped to make it treated as non-IKI data by prepending a backslash "\" before the colon ":" that is before the opening quote (single or double). Potential IKI data refers to any valid IKI sequence without considering the closing single quote "'" or closing double quote """. Unicode punctuation connector characters are supported just like "_", except when they connect outside the current line (such as U+FE33 "︳"). - Unicode invisible punctuations (such as invisible plus: U+2064) are not considered a punctuations in this standard (because they a zero-width characters), therefore they are not to be considered a valid '_', '-', or '+' Unicode equivalents. + Unicode invisible punctuations (such as invisible plus: U+2064) are not considered a punctuations in this standard (because they a zero-width characters), therefore they are not to be considered a valid "_", "-", or "+" Unicode equivalents. Key\: - \o = any printable word character, including "_", "-", "+" (and Unicode equivalents). - \c = any character, including whitespace and non-printing, and any delimited quote (used as the opening quote) or a any quote (undelimited) not used as the opening quote. - \q = either a single quote (') or a double quote ("). - \x = any character. - \W = any non-word character, discluding "_", "-", "+" (and Unicode equivalents). - \e = an optional escape sequence of any number of backslashes, such as "\". - * = 0 or more occurrences. - ~ = one or more occurrences, or 0 if at start of file. + "\o" = any printable word character, including "_", "-", "+" (and Unicode equivalents). + "\c" = any character, including white space and non-printing, and any delimited quote (used as the opening quote) or a any quote (undelimited) not used as the opening quote. + "\q" = either a single quote "'" or a double quote """. + "\x" = any character. + "\W" = any non-word character, discluding "_", "-", "+" (and Unicode equivalents). + "\e" = an optional escape sequence of any number of backslashes, such as "\". + "*" = zero or more occurrences. + "~" = one or more occurrences, or zero if at start of file. Before Structure\: - \x*\W~\*:* + "\x*\W~\*:*" Structure\: - \o\e:\q\c\q + "\o\e:\q\c\q" After Structure\: + "" Example\: - # fss-000c iki-0000 + code:'# fss-000c iki-0000 This is my sentence, anything can go here but sometimes I want to emphasis:"emphasize some text". @@ -52,7 +53,7 @@ IKI Specifications: Quotes may be included, such as: code:"const char *string = \"My \\\"quoted\\\" C string.\";". - The following emphasis\:"is escaped to not be treated as IKI data". + The following emphasis:"is escaped to not be treated as IKI data".' Objects would be\: 1) emphasis @@ -63,3 +64,8 @@ IKI Specifications: 1.1) emphasize some text 2.1) http://www.example.com/url with space/ 3.1) const char *string = "My \"quoted\" C string."; + + The following are core specifications (each with a common name associated with the specification number)\: + - fss-0000: Unrestricted + - fss-0001: Basic + - fss-0002: Simple Script diff --git a/fll/design.html b/fll/design.html index e771f1c..908ec31 100644 --- a/fll/design.html +++ b/fll/design.html @@ -52,7 +52,7 @@
Back
-
+
Featureless Linux Library
diff --git a/fll/specifications.html b/fll/specifications.html index 4830e4a..3fdc589 100644 --- a/fll/specifications.html +++ b/fll/specifications.html @@ -52,14 +52,11 @@
Back
-
+
Featureless Linux Library
Specifications
- About -
-
Featureless Settings Specifications
@@ -170,8 +167,8 @@

@@ -423,7 +420,7 @@ Object_2 This is multiple\" Contents and the trailing quote does not need to be

Example File: 

-# fss-000c iki-0000
+# FSS-000C iki-0000
 
 This is my sentence, anything can go here but sometimes I want to emphasis:"emphasize some text".
 
diff --git a/fll/specifications/fss/fss-0000.html b/fll/specifications/fss/fss-0000.html
index 9138ea9..d810363 100644
--- a/fll/specifications/fss/fss-0000.html
+++ b/fll/specifications/fss/fss-0000.html
@@ -53,7 +53,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-0001.html b/fll/specifications/fss/fss-0001.html
index f6da3af..09a62bc 100644
--- a/fll/specifications/fss/fss-0001.html
+++ b/fll/specifications/fss/fss-0001.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-0002.html b/fll/specifications/fss/fss-0002.html
index 00ce0b5..8884443 100644
--- a/fll/specifications/fss/fss-0002.html
+++ b/fll/specifications/fss/fss-0002.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-0003.html b/fll/specifications/fss/fss-0003.html
index c6b9020..a256f77 100644
--- a/fll/specifications/fss/fss-0003.html
+++ b/fll/specifications/fss/fss-0003.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-0004.html b/fll/specifications/fss/fss-0004.html
index c730254..7c03730 100644
--- a/fll/specifications/fss/fss-0004.html
+++ b/fll/specifications/fss/fss-0004.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-0005.html b/fll/specifications/fss/fss-0005.html
index 543d290..9bc4e0e 100644
--- a/fll/specifications/fss/fss-0005.html
+++ b/fll/specifications/fss/fss-0005.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-0006.html b/fll/specifications/fss/fss-0006.html
index ddfe7de..7d6cd31 100644
--- a/fll/specifications/fss/fss-0006.html
+++ b/fll/specifications/fss/fss-0006.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-0007.html b/fll/specifications/fss/fss-0007.html
index 6b71b82..b8758bf 100644
--- a/fll/specifications/fss/fss-0007.html
+++ b/fll/specifications/fss/fss-0007.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-0008.html b/fll/specifications/fss/fss-0008.html
index b0e99b7..53d7f54 100644
--- a/fll/specifications/fss/fss-0008.html
+++ b/fll/specifications/fss/fss-0008.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-0009.html b/fll/specifications/fss/fss-0009.html
index 9f83630..61f7f47 100644
--- a/fll/specifications/fss/fss-0009.html
+++ b/fll/specifications/fss/fss-0009.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-000a.html b/fll/specifications/fss/fss-000a.html
index d394326..fc25da3 100644
--- a/fll/specifications/fss/fss-000a.html
+++ b/fll/specifications/fss/fss-000a.html
@@ -1,7 +1,7 @@
 
 
   
-    FLL - Specifications - FSS-000A (Extended Reverse Mapping)
+    FLL - Specifications - fss-000a (Extended Reverse Mapping)
 
     
 
@@ -54,12 +54,12 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

           

-            
FSS-000A
(Extended Reverse Mapping)

+            
fss-000a
(Extended Reverse Mapping)

           

           

             …
@@ -76,7 +76,7 @@
 
           

             

-              
FSS-000A (Extended Reverse Mapping)

+              
fss-000a (Extended Reverse Mapping)

             

 
             

diff --git a/fll/specifications/fss/fss-000b.html b/fll/specifications/fss/fss-000b.html
index e2aa5c1..2413fd3 100644
--- a/fll/specifications/fss/fss-000b.html
+++ b/fll/specifications/fss/fss-000b.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-000c.html b/fll/specifications/fss/fss-000c.html
index c3db269..de97e38 100644
--- a/fll/specifications/fss/fss-000c.html
+++ b/fll/specifications/fss/fss-000c.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-000d.html b/fll/specifications/fss/fss-000d.html
index f924021..aab5d1c 100644
--- a/fll/specifications/fss/fss-000d.html
+++ b/fll/specifications/fss/fss-000d.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-000e.html b/fll/specifications/fss/fss-000e.html
index 160ce13..d7ea884 100644
--- a/fll/specifications/fss/fss-000e.html
+++ b/fll/specifications/fss/fss-000e.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/fss/fss-000f.html b/fll/specifications/fss/fss-000f.html
index 07dcb10..ca53710 100644
--- a/fll/specifications/fss/fss-000f.html
+++ b/fll/specifications/fss/fss-000f.html
@@ -53,7 +53,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
FSS

           

diff --git a/fll/specifications/iki/iki-0000.html b/fll/specifications/iki/iki-0000.html
index d96719a..aba3156 100644
--- a/fll/specifications/iki/iki-0000.html
+++ b/fll/specifications/iki/iki-0000.html
@@ -53,7 +53,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
IKI

           

diff --git a/fll/specifications/iki/iki-0001.html b/fll/specifications/iki/iki-0001.html
index 3f89955..b857e06 100644
--- a/fll/specifications/iki/iki-0001.html
+++ b/fll/specifications/iki/iki-0001.html
@@ -54,7 +54,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
IKI

           

diff --git a/fll/specifications/iki/iki-0002.html b/fll/specifications/iki/iki-0002.html
index cbd0790..c855128 100644
--- a/fll/specifications/iki/iki-0002.html
+++ b/fll/specifications/iki/iki-0002.html
@@ -53,7 +53,7 @@
           

             Back
           

-          

+          

             
FLL Specification

             
IKI

           

diff --git a/news/2022_05_01-website_redesign.html b/news/2022_05_01-website_redesign.html
index 6ec5676..fe83be9 100644
--- a/news/2022_05_01-website_redesign.html
+++ b/news/2022_05_01-website_redesign.html
@@ -52,7 +52,7 @@
           

             Back
           

-          

+          

             
2022 / 05 / 01

             
Website Redesign

           

diff --git a/news/2022_05_06-basic_program_documentation.html b/news/2022_05_06-basic_program_documentation.html
index cb60d2d..e0704a6 100644
--- a/news/2022_05_06-basic_program_documentation.html
+++ b/news/2022_05_06-basic_program_documentation.html
@@ -52,7 +52,7 @@
           

             Back
           

-          

+          

             
2022 / 05 / 06

             
Basic Program Documentation

           

diff --git a/news/2022_05_16-fll_specifications_added.html b/news/2022_05_16-fll_specifications_added.html
index c3a6a1f..998409e 100644
--- a/news/2022_05_16-fll_specifications_added.html
+++ b/news/2022_05_16-fll_specifications_added.html
@@ -52,7 +52,7 @@
           

             Back
           

-          

+          

             
2022 / 05 / 16

             
FLL Specifications Added

           

diff --git a/news/2022_06_04-librem_to_freedom.html b/news/2022_06_04-librem_to_freedom.html
index a58d55c..22ebabe 100644
--- a/news/2022_06_04-librem_to_freedom.html
+++ b/news/2022_06_04-librem_to_freedom.html
@@ -52,7 +52,7 @@
           

             Back
           

-          

+          

             
2022 / 06 / 04

             
Librem to Freedom

           

diff --git a/news/2022_07_02-fll_0_5_10_release.html b/news/2022_07_02-fll_0_5_10_release.html
index 702005d..b6a3737 100644
--- a/news/2022_07_02-fll_0_5_10_release.html
+++ b/news/2022_07_02-fll_0_5_10_release.html
@@ -52,7 +52,7 @@
           

             Back
           

-          

+          

             
2022 / 07 / 02

             
FLL 0.5.10 Release

           

diff --git a/projects.html b/projects.html
index 206a64b..430dfdb 100644
--- a/projects.html
+++ b/projects.html
@@ -284,8 +284,8 @@
             
             

               

-                This is a program implementing the Featureless Settings Specification FSS-0000 (Basic).

-                This performs read operations related to the FSS-0000 (Basic) standard.
+                This is a program implementing the Featureless Settings Specification FSS-0000 (Basic).

+                This performs read operations related to the FSS-0000 (Basic) standard.
               

             

           
@@ -296,8 +296,8 @@
             
             

               

-                This is a program implementing the Featureless Settings Specification FSS-0000 (Basic).

-                This performs write operations related to the FSS-0002 (Basic) standard.
+                This is a program implementing the Featureless Settings Specification FSS-0000 (Basic).

+                This performs write operations related to the FSS-0002 (Basic) standard.
               

             

           
@@ -308,8 +308,8 @@
             
             

               

-                This is a program implementing the Featureless Settings Specification FSS-0002 (Basic List).

-                This performs read operations related to the FSS-0002 (Basic List) standard.
+                This is a program implementing the Featureless Settings Specification FSS-0002 (Basic List).

+                This performs read operations related to the FSS-0002 (Basic List) standard.
               

             

           
@@ -320,8 +320,8 @@
             
             

               

-                This is a program implementing the Featureless Settings Specification FSS-0002 (Basic List).

-                This performs write operations related to the FSS-0002 (Basic List) standard.
+                This is a program implementing the Featureless Settings Specification FSS-0002 (Basic List).

+                This performs write operations related to the FSS-0002 (Basic List) standard.
               

             

           
@@ -332,8 +332,8 @@
             
             

               

-                This is a program implementing the Featureless Settings Specification FSS-0008 (Embedded List).

-                This performs read operations related to the FSS-0008 (Embedded List) standard.
+                This is a program implementing the Featureless Settings Specification FSS-0008 (Embedded List).

+                This performs read operations related to the FSS-0008 (Embedded List) standard.
               

             

           
@@ -344,8 +344,8 @@
             
             

               

-                This is a program implementing the Featureless Settings Specification FSS-0008 (Embedded List).

-                This performs write operations related to the FSS-0008 (Embedded List) standard.
+                This is a program implementing the Featureless Settings Specification FSS-0008 (Embedded List).

+                This performs write operations related to the FSS-0008 (Embedded List) standard.
               

             

           
@@ -356,8 +356,8 @@
             
             

               

-                This is a program implementing the Featureless Settings Specification FSS-0001 (Extended).

-                This performs read operations related to the FSS-0001 (Extended) standard.
+                This is a program implementing the Featureless Settings Specification FSS-0001 (Extended).

+                This performs read operations related to the FSS-0001 (Extended) standard.
               

             

           
@@ -368,8 +368,8 @@
             
             

               

-                This is a program implementing the Featureless Settings Specification FSS-0001 (Extended).

-                This performs write operations related to the FSS-0001 (Extended) standard.
+                This is a program implementing the Featureless Settings Specification FSS-0001 (Extended).

+                This performs write operations related to the FSS-0001 (Extended) standard.
               

             

           
@@ -380,8 +380,8 @@
             
             

               

-                This is a program implementing the Featureless Settings Specification FSS-0003 (Extended List).

-                This performs read operations related to the FSS-0003 (Extended List) standard.
+                This is a program implementing the Featureless Settings Specification FSS-0003 (Extended List).

+                This performs read operations related to the FSS-0003 (Extended List) standard.
               

             

           
@@ -392,8 +392,8 @@
             
             

               

-                This is a program implementing the Featureless Settings Specification FSS-0003 (Extended List).

-                This performs write operations related to the FSS-0003 (Extended List) standard.
+                This is a program implementing the Featureless Settings Specification FSS-0003 (Extended List).

+                This performs write operations related to the FSS-0003 (Extended List) standard.
               

             

           
@@ -404,11 +404,11 @@
             
             

               

-                This is a program implementing the Featureless Settings Specification FSS-000E (Payload).

-                This performs read operations related to the FSS-000E (Payload) standard.

+                This is a program implementing the Featureless Settings Specification FSS-000E (Payload).

+                This performs read operations related to the FSS-000E (Payload) standard.

               

               

-                The FSS-000E (Payload) is focused on network communication and is intended to be used inside a network packet.

+                The FSS-000E (Payload) is focused on network communication and is intended to be used inside a network packet.

                 This program can be used to manually read a network packet or data from the network.
               

             

@@ -420,11 +420,11 @@
             
             

               

-                This is a program implementing the Featureless Settings Specification FSS-000E (Payload).

-                This performs write operations related to the FSS-000E (Payload) standard.

+                This is a program implementing the Featureless Settings Specification FSS-000E (Payload).

+                This performs write operations related to the FSS-000E (Payload) standard.

               

               

-                The FSS-000E (Payload) is focused on network communication and is intended to be used inside a network packet.

+                The FSS-000E (Payload) is focused on network communication and is intended to be used inside a network packet.

                 This program can be used to manually write the payload portion of a network packet.
               

             

@@ -467,8 +467,8 @@
             
             

               

-                Similar to the FSS Read programs, this is a program implementing the Featureless Settings Specification IKI-0000 (Unrestricted).

-                This performs read operations related to the Unrestricted IKI standard (IKI-0000).

+                Similar to the FSS Read programs, this is a program implementing the Featureless Settings Specification iki-0000 (Unrestricted).

+                This performs read operations related to the iki-0000 (Unrestricted) standard.

               

               

                 The IKI settings specification plays on how it is simpler than a Wiki syntax.

@@ -487,8 +487,8 @@
             
             

               

-                Similar to the FSS Write programs, this is a program implementing the Featureless Settings Specification IKI-0000 (Unrestricted).

-                This performs write operations related to the Unrestricted IKI standard (IKI-0000).

+                Similar to the FSS Write programs, this is a program implementing the Featureless Settings Specification iki-0000 (Unrestricted).

+                This performs write operations related to the iki-0000 (Unrestricted) standard.

               

               

                 The IKI settings specification plays on how it is simpler than a Wiki syntax.

diff --git a/specification.html b/specification.html
new file mode 100644
index 0000000..f076428
--- /dev/null
+++ b/specification.html
@@ -0,0 +1,322 @@
+
+
+  
+    Kevux Systems and Software - Documentation
+
+    
+
+    
+    
+    
+    
+    
+
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+
+    
+    
+    
+    
+    
+  
+
+  
+    

+
+    

+      
+
+      

+        

+          

+            
Documentation

+          

+
+          

+            

+              
Projects

+            

+
+            

+              

+                Documentation for the following projects are provided within their own sub-pages.
+              

+              

+                
Byte Dump

+                
Control

+                
Controller

+                
Featureless Make

+                
Firewall

+                
FSS Identify

+                
FSS Basic Read

+                
FSS Basic Write

+                
FSS Basic List Read

+                
FSS Basic List Write

+                
FSS Embedded List Read

+                
FSS Embedded List Write

+                
FSS Extended Read

+                
FSS Extended Write

+                
FSS Extended List Read

+                
FSS Extended List Write

+                
FSS Payload Read

+                
FSS Payload Write

+                
FSS Status Code

+                
Status Code

+                
IKI Read

+                
IKI Write

+                
UTF8

+              

+              
    
+              

+            

+          

+
+          

+            

+              
Specifications

+            

+
+            

+              

+                Projects like the Featureless Linux Library are focused entirely around provided standards for every aspect of the project. Numerous specifications are available describing these standards. At this time, the specifications have not been transcribed into a format for the web. They are stored in plain text within the source code repositories.
+              

+              

+                Many of these specifications may be found here:
+              

+              
+            

+          

+
+          

+            

+              
APIs

+            

+
+            

+              

+                The APIs have not yet been generated and are not available in an easy to consume form outside of the source code itself.
+              

+              

+                The API can be viewed by navigating the source code for the FLL here:
+              

+              
+            

+          

+
+          

+            

+              
Terminology

+            

+
+            

+              

+                One of the biggest problems with an API is the mis-use or misunderstanding of the meaning and purpose of one. The term itself is not the most accurate and is also not ideal. A more appropriate term would be a Library Interface or a Software Interface.
+              

+
+              

+                

+                  
Standard

+                

+
+                

+                  

+                    A set of rules and guidelines.
+                  

+                

+              

+
+              

+                

+                  
Specification

+                

+                

+                  

+                    A specific interpretation, clarification, or description of a Standard, such as the documentation that describes how to use or follow a Standard.
+                  

+                

+              

+
+              

+                

+                  
Implementation

+                

+                

+                  

+                    The applying of some Standard or Specification.
+                  

+                

+              

+
+              

+                

+                  
Application Programming Interface (API)

+                

+                

+                  

+                    The API term is commonly mis-represented as Services or Protocols (such as "Web API"). An API instructs a programmer how to use a dependency when programming some software that utilizes said dependency. An API is a Specification of some Implementation of a Standard be it a formally defined standard or an informally defined standard. An API may be an Implementation of a Standard or a part of an Implementation of a Standard. An API is, in effect, documentation.
+                  

+                

+              

+
+              

+                

+                  
Application Binary Interface (ABI)

+                

+                

+                  

+                    The ABI term refers to an Application Binary Interface and represents the compiled implementation of some API. An ABI may not always exist for some API, such as for pure scripting languages. An ABI is neither a Specification nor a Standard. An ABI is an Implementation of an API making it an Implementation of a Standard or Specification.
+                  

+                

+              

+
+              

+                

+                  
Service

+                

+                

+                  

+                    Any action or labor performed by one party for another party (such as one person helping another person).
+                  

+                

+              

+
+              

+                

+                  
Protocol

+                

+                

+                  

+                    In the context of computers and software, this is a Standard focused on communication between two parties (often referring to Internet communication).
+                  

+                

+              

+            

+          

+        

+      

+    

+  
+
-- 
1.8.3.1