From 37ea0c0496893b98d63e43c72fe75699b2237242 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Sun, 3 Jul 2022 17:28:22 -0500 Subject: [PATCH] Update: Add Design and Principles pages. This prepares the website for the additional documentation on the FLL project. Many of the text files from the "documents" directory will be transcribed into pages under this. One such example would be the style_guide.txt file. Includes miscellaneous changes. Update the sources, preparing another website download package as of this commit. --- distributions.html | 2 +- fll.html | 3 + fll/design.html | 200 ++++++++++++++++++++++++++++++++++++++++++++++++ fll/specifications.html | 106 ++++++++++++------------- sources.html | 2 +- 5 files changed, 258 insertions(+), 55 deletions(-) create mode 100644 fll/design.html diff --git a/distributions.html b/distributions.html index ac4c804..36d76c7 100644 --- a/distributions.html +++ b/distributions.html @@ -110,7 +110,7 @@
-
+

About Releases and Scripts

diff --git a/fll.html b/fll.html index e8633cf..2ae0a21 100644 --- a/fll.html +++ b/fll.html @@ -61,6 +61,9 @@
Specifications
+
+ Design and Principles +
… Collapse Menu diff --git a/fll/design.html b/fll/design.html new file mode 100644 index 0000000..e771f1c --- /dev/null +++ b/fll/design.html @@ -0,0 +1,200 @@ + + + + FLL - Design and Principles + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+

Featureless Linux Library

+
+ +
+
+

Design and Principles

+
+ +
+

+ The Featureless Linux Library has a specific design with a specific set of principles. This design and these principles direct and govern how, what, and in what way the projects are built, styled, released, maintained, documented, and evolved. +

+

+ The FLL project is a collection of different sub-projects, standards, specifications, and programs. Each of these has its own set of rules, guidelines, and principles. All of these are primarily drive by open-source design and principles but the specific way in which this happens is dependent on the specific type of material or data as well as the intended purpose or target audience. +

+
+
+ +
+
+

Core Perspectives

+
+ +
+

+ To better understand the core principles and even philosophy behind this FLL project one must first understand some key terminology from the perspective of what the terms do or are for rather than what the direct meaning of the words are. +

+

+ The term software is understood as thought. That is to say, if you have an idea in your mind then treat this idea as software. This perspective introduces a problem, a problem of ambiguity. Software is more than an idea when it is on a computer. The general definition of software can refer to source code, binaries, or data (data encompasses both source code and binaries but for the purposes here please ignore this fact). A binary is usually created from source code. +

+

+ The perspective on source code should be described first to address the problem. Source Code is an idea communicated through some language. A single idea may be expressed differently between two distinct languages and still be the same idea. However, the representation of that idea may be limited or otherwise influenced by the constraints or limitation of a language. +

+

+ When the source code is compiled, interpreted, or otherwise converted into machine code, the idea behind the source code is now represented in a new language, the machine language. This resulting representation in the machine language is the binary. +

+

+ At this point the software, be it the source code or the binary is synonymous with spoken words. There is no product, only just a spoken and recored idea constrained by the language it is spoken in. +

+

+ The magic happens when the machine computes. This computation of the communicated idea requires hardware. It is this hardware that manifests the idea into reality. A product, therefore, may only exist in conjunction with some hardware. +

+

+ The world as it currently exists is a world of restrictions and patents. Supposedly an idea is not patentable. Supposedly math cannot be patented. Yet with software effectively being a written or spoken idea, often represented in mathematical equations, is treated as patentable. +

+

+ Associating, or otherwise linking, an idea is somehow treated as if the originator of the first spoken idea spoke the second idea. Take a conversation, for example. If the first person says "I like cake." and the second person says "I like candles on cake." then does that mean the first person is the one who originated the statement "I like candles on cake."? Of course not. But the legal system in the United States of America, and perhaps the world, have decided otherwise. That is to say, linking one binary to another (somehow) creates a combined product. This appears to be some sort of magical fairy dust lawyers use to convince people that what you are smelling is actually a rose rather than something bovine herders have to shovel up from time to time. +

+

+ The core principle of this project is to use legal means to make such an absurdity illegal. Thus the copyrights, such as the LGPLv2.1+ license, are utilized. The goal here is not to deny a person the ability to make a product and sell it. Instead, the goal here is so that a person who makes a product can actually make and sell it. Just because a bird house has nails in it doesn't mean the originator of the nails now owns all rights to the bird house. Just because an AMD motherboard has an Nvidia graphics card connected to it does not mean AMD now owns all rights to the Nvidia graphics card. +

+

+ The FLL is a set of nails, screws, gears, and clockwork all designed and intended to be taken apart and used in whatever way another person deems necessary. For convenience, this library includes fully functionaly programs as an example on how to use the project. They too can be taken apart. +

+
+
+ +
+
+

Core Design

+
+ +
+

+ The FLL project, sub-projects, and related projects are all being built in stages. These stages are not temporal based but are instead goal based. There are temporal constraints to keep development within reason and to provide cut-off points. Each of these goal posts are separated by development and stable releases. A stable release may also be referred to as a production release. +

+

+ Long term stability is a flag ship goal of this project. To that extent, stable releases are to be maintained indefinitely. Ideally, this will hold true only for 1.0 releases and beyond but in practice pre-1.0 may also seek this goal. For long term stability, API breakage is not allowed with a stable release. For those people out there who blindly apply infinites to everything, stop it. If there is some major security issue or other such extreme problem then API breakage can be considered. This will, however, be strongly resisted to ensure only necessary breakage occurs. Strong resistence is not the same as never allowing. +

+

+ The term "featureless" is loosely used in this project to describe the idea that a project should not constantly add features like a kid in a candy shop wanting to try every new piece of candy they find. The entire FLL project is designed so that you can do as you will so long as you do not deny another person the same. This means that you are free to add as many features as you like. In your own project. Or in your own hacked variation. This project shall attempt to maintain a discrete set of functionality specific to each stable release and the goals of that release. +

+

+ Temporal constraints may result in a stable release being made without all of the intended features. These such cases should be treated on a per-situation basis. Changes to a stable release to add features that did not make it is still discouraged and should be avoided. Futhermore, there is an undescribed point in time in which if a stable release has not achieve a planned or intended feature then that feature should never be added. Time matters. For example, if version 1.0 was supposed to bake a cake and failed to get that functionality but then 10-years later (when 3d-printing evolved into 3d-baking) the version 1.0 must not have the "bake a cake" feature added. Too much time has passed. Just make a 1.2 release for baking cakes. The rule of thumb is flexibility for short term and rigidity for long term. +

+

+ The FLL project has the word "library" in the name. For good reason. The primary purpose of this project is to be used as a library. The original flag ship of this project is the Featureless Make program. Notice the word "program". The FLL project does contain related programs but these are kept to a minimal. The purpose of the programs in this project are to have fully functional and usable example programs. They are not examples in the traditional sense but are instead full blown implementations. +

+

+ The Featureless Make is also an exception case. I wrote a thesis regarding the GNU make system and I proposed the Featureless Make as a solution that utilizes the Featureless Settings Specification. This is the foundation that birthed the Featureless Linux Library. For this reason, the Featureless Make will always be part of the FLL project. +

+

+ Many of the programs provided by the FLL are a way of extending the library in such a way that a shell script, such as GNU Bash, can utilize the library. Programs like the FSS Basic Read are examples of this. +

+

+ Other programs, namely the Controller program are not intended to be directly part of this project in the long term. They exist within this project for development convenience. Eventually they will budd off into their own separate project. These separate projects will still depend on and use the FLL. +

+

+ The way in which data is stored, utilized, and communicated should also follow similar design and principles. The standards and their accompanying specifications are provided by the FLL to achieve this. +

+

+ Keep it simple is one of the goals of the project. But again, all of you people out there that love infinitives, stop it. This project follows "keep it simple" rather than "keep it absolutely simple". There are many situations where complexity is not only encouraged but also necessary. +

+
+
+ +
+
+

Art of Communication

+
+ +
+

+ An important aspect of the design and principles of the FLL project is that of communication. All aspects of the project are designed to have both explicit and implicit meaning. From the syntax and styling to the standards and protocols. +

+

+ The project hosts numerous plain text files following a given FSS format. The IKI format may be used in many of these files to provide further assistance in communicating different aspects of the documentation. +

+

+ These text files are then process either through scripts or manually and presented in different formats. One such format is on the Kevux website where this document might reside. This results in a bit of redudancy and complexity but achieves the goal of communication. +

+

+ Idealistically the FLL project will be written in multiple programming languages. This would mean that the ideas represented by this project are communicated through different software languages. Given the complexity of this task, this is not a goal post but is instead an ideal. To that end, the design of the FLL and related projects is done in such a way to be open-ended and better allow for additional languages even if no additional language is ever used. +

+
+
+
+
+
+ + diff --git a/fll/specifications.html b/fll/specifications.html index 24e0150..4830e4a 100644 --- a/fll/specifications.html +++ b/fll/specifications.html @@ -147,10 +147,10 @@
-

+

The Featureless Linux Library defines several standards for use in this project. Many of these standards are defined via the Featureless Settings Specifications. Most of these are focused on settings files (configuration files) but are written general enough to support a wide range of uses. The original project that the FLL project is built around is the Featureless Make program, also called Fake. The Fake program is a great example on how the FSS are intended to be used.

-

+

The standards are not limited to those defined in the FSS. There are the IKI standards (which is not an acronym). The term IKI plays off of the term Wiki. The IKI standard is intended to have simpler syntax than a Wiki syntax and is used in several FLL projects and even inside standards defined by FSS.

@@ -162,10 +162,10 @@
-

+

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.

-

+

The FSS defines the following:

    @@ -178,7 +178,7 @@
  • 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 consists of two main parts: an Object and the Content.

@@ -191,12 +191,12 @@
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.

-

+

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. @@ -204,11 +204,11 @@ 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). These specifications refer to characters that have printable representation as printable. @@ -221,21 +221,21 @@ 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.

-

+

Unless otherwise specified, white space may exist to the left of the start of Objects. Unless otherwise specified, white space may exist to the right of the end of Objects, but only if that given Object is properly quoted and the white space is after the terminating quote but before any Content.

-

+

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, 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.

-

+

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.
 "Object \"3" 'Wouldn't require delimits if no white space or end of string after.'
-

+

Unlike this specification, a more traditional delimit process would have the above three lines instead represented as: 

 "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.
 "Object \\"3" 'Wouldn\'t require delimits if no white space or end of string after.'
-

+

These examples would resolve as follows: 

 1) Object\:
@@ -295,12 +295,12 @@ Object_2 This is multiple\" Contents and the trailing quote does not need to be
    Content\:
   - Wouldn't require delimits if no white space or end of string after.
-

+

All specifications are expected to support or be of the character encoding UTF-8; however, there is no imposed restriction on supporting or using any other encoding. 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. 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. @@ -308,7 +308,7 @@ Object_2 This is multiple\" Contents and the trailing quote does not need to be 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.

-

+

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. @@ -316,25 +316,25 @@ Object_2 This is multiple\" Contents and the trailing quote does not need to be 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.

-

+

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.

-

+

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).

-

+

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.

-

+

The following are core specifications (each with a common name associated with the specification number):

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

    +

    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 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.

    -

    +

    A potential IKI variable name starts on word (or _, -, +) characters. 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 code::" that is before the opening quote (single or double).

    -

    +

    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.

    -

    +

    Key:

      @@ -402,25 +402,25 @@ Object_2 This is multiple\" Contents and the trailing quote does not need to be
    • * = zero or more occurrences.
    • ~ = one or more occurrences, or zero if at start of file.
    -

    +

    Before Structure:

    • \x*\W~\*:*
    -

    +

    Structure:

    • \o\e:\q\c\q
    -

    +

    After Structure:

    -

    +

    Example File: 

     # fss-000c iki-0000
@@ -435,7 +435,7 @@ Quotes may be included, such as: code:"const char *string = \"My \\\"quoted\\\"
 
 The following emphasis\:"is escaped to not be treated as IKI data".
    -

    +

    Example Results: 

     Objects would be:
@@ -448,7 +448,7 @@ Contents would be:
   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):

      @@ -465,34 +465,34 @@ Contents would be:
      -

      +

      The Completeness Theorem represents an informal theory by Kevin Day focusing on how software should be complete. The theory has not been formalized and the following is a basic explanation. A formal definition may be provided in the future.

      -

      +

      When developing software, one should not program for the minimum requirements. Instead, one should consider the scope of the project and its intended design. Taking that into consideration all functionality needed to achieve this should be considered and implemented.

      -

      +

      The most common misconceptions about this theorem is that it is not about writing all possible combinations, permutations, possibilities, etc. In fact, it is more accurate to say the opposite. The key focus is figuring out what the scope and intended functionalities are and make sure to achieve those.

      -

      +

      This does not conflict with KISS but instead complements it.

      -

      +

      If this is not clear, then consider thinking of things this way. The KISS focuses on keeping the design and process simple. The Completeness Theorem focuses on making sure the design is complete.

      -

      +

      Now if, say a car, is designed to follow KISS but violates the Completeness Theorem, then that car could be built without doors. Not having doors simplifies the car. It is much simpler and easier to get in and out of.

      -

      +

      Using that example, a car designed to follow both KISS and the Completeness Theorem would have doors.

      -

      +

      To better understand the Completeness Theorem, again take the car example. If the car is intended to be used only in say photo shoots and is not in any way intended ever to be used, then as per the Completeness Theorem, the car would not need an engine. Whereas a car designed and intended to be used that does not have an engine would fail to follow the Completeness Theorem.

      -

      +

      The Completeness Theorem is subjective and is intended to be used as a guide.

      -

      +

      The Completeness Theorem asserts that perfection is impossible and pointless and one must instead understand what is necessary to complete the project rather than to handle all possibilities. Simply because perfection isn't possible doesn't mean one must lower their standards or have no standards. Determine what is or is not needed to complete the project and meet that rather than meet less than that.

      @@ -546,13 +546,13 @@ Contents would be:
      A Web Service Interface is a new term created so that this project can more appropriately communicate the concept of a web service. A Web Service Interface describes the interface in which to communicate to and receive response from a web service and is described by or adheres to some web protocol.
    -

    +

    Based on this terminology, a standard is the representation of some set of rules and guidelines, however it is the specification that actually defines and describes those roles. The last 'S' in FSS can therefore be used to represent either "standard" or "specification" in casual speech. Given that an implementation is not a standard, an implementation can deviate from the standard (or the specification of some standard). Such deviations do not alter the standard nor do they alter the specification.

    -

    +

    Good documentation practices suggest the documentation of an implementation. It is very easy to confuse the specification of an implementation of some standard with the specification of the standard itself. This has happened several times in history where some implementation violates the standard but despite being non-standard that implementation becomes popular. When the specification of that, now non-standard, implementation becomes popularized, those properly following the specification of the standard tend to suffer.

    -

    +

    This project encourages deviations from the standards and such actions are allowed and protected by the copyright licenses. However, this project discourages communicating compliance of some standard when something is, in fact, not compliant. Problems in the interpretation of a standard fall under communication problems and are not considered deviations from the standard even though it may technically be a deviation. It is for these reasons that the terminology has been explicitly defined, clarified, and presented on this page.

    diff --git a/sources.html b/sources.html index 39f2e26..0b4a905 100644 --- a/sources.html +++ b/sources.html @@ -150,7 +150,7 @@ The following is the link:

    Most of the changes for this website are also made publicly available through repositories hosted on third-party websites and services. -- 1.8.3.1