From e9621b09db34cfd9ac6264c77068c34afa5bfb17 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Mon, 18 Nov 2024 20:17:38 -0600 Subject: [PATCH] Bugfix: The IKI and EKI specifications have mistakes and needs clarifications. The wording of the specification is now greatly improved. I noticed that some of the specification is actually incomplete. I removed the incomplete sentence. Make sure the FSS-000C specification is updated to add allowances for the EKI specification. The example in both the IKI and the EKI specifications has several mistakes. Use the grave character (U+0060) for the code to help avoid needing to escape the single quotes. The IKI inside of a valid IKI Variable do not need to be escaped. The example that directly states "is escaped to not be treated as IKI Variable" is incorrectly being documented as a valid IKI syntax (a significant mistake on my part). Add explicit escaping examples to help make the escape behavior more explicit and clear. I believe the current escaping logic in the IKI processing code is incorrect and will need to be updated and corrected following this commit. I remembered this time to make the date based on UTC. The version date in this commit is based on the current UTC Earth day. --- specifications/eki.txt | 71 ++++++++++++++++----------- specifications/fss-000c.txt | 22 +++++++-- specifications/iki.txt | 115 ++++++++++++++++++++++++++++---------------- 3 files changed, 135 insertions(+), 73 deletions(-) diff --git a/specifications/eki.txt b/specifications/eki.txt index ae36114..7ef68b4 100644 --- a/specifications/eki.txt +++ b/specifications/eki.txt @@ -1,13 +1,13 @@ # fss-0002 iki-0000 # # license open-standard-license-1.0-or-later -# version 2024/11/10 +# version 2024/11/19 # # This file (assumed to be named eki.txt) can be more easily read using the following iki_read commands: # iki_read eki.txt +Q -w -WWW character "'" "'" code '"' '"' italic '"' '"' # # To read the "EKI Specifications" section of this file, use this command sequence: -# fss_basic_list_read iki.txt +Q -cn "EKI Specifications" | iki_read +Q -w -WWW character "'" "'" code '"' '"' italic '"' '"' +# fss_basic_list_read eki.txt +Q -cn "EKI Specifications" | iki_read +Q -w -WWW character "'" "'" code '"' '"' italic '"' '"' # EKI Specifications: @@ -45,44 +45,61 @@ EKI Specifications: code:"" Example\: - code:'# fss-000c eki-0000 + code:`# fss-000c eki-0000 - This is my sentence, anything can go here but sometimes I want to italic\:"emphasize some text". + This is my sentence, anything can go here but sometimes I want to italic:"emphasize some text". - Other times I want to render a url with bold such as this example url: bold:url\:\'http://www.example.com/url with space/\'. + Other times I want to render a URL with bold such as this example URL: bold:url:'http://www.example.com/url with space/'. - There are no comments, except for maybe the FSS\:"Featureless Settings Specification" header (which would not resolve to any EKI syntax anyway). + There are no comments, except for maybe the FSS:"Featureless Settings Specification" header (which would not resolve to any EKI syntax anyway). - Quotes may be included, such as: code\:"const char *string = \"My \\\"quoted\\\" C string.\";". + Quotes may be included, such as: code:"const char *string = \"My \\\"quoted\\\" C string.\";". The following bold:italic\:"is escaped to not be treated as EKI data". - The conditionally optional open and close brackets allow for putting a variable directly next to another word character like: [context]\:"bold"this[context]\:"bold".' + The conditionally optional open and close brackets allow for putting a variable directly next to another word character like: [context]:"bold"this[context]:"bold". Multiple Objects within a bracket is also valid, like: before[bold:context]:"important"after. + These are examples of escapes: one:"\" escape", two:"\\" escape", three:"\\\" escape", six:"\\\\\\" escape". + + These are examples of non-escapes: one:"\' escape", two:"\\' escape", three:"\\\' escape", six:"\\\\\\' escape".` + Objects (also called vocabulary or variable name) would be\: - 1.1) italic - 2.1) bold - 2.2) url - 3.1) FSS - 4.1) code - 5.1) bold - 5.2) italic - 6.1) context - 7.1) context - 8.1) bold - 8.2) context + 1.1) italic + 2.1) bold + 2.2) URL + 3.1) FSS + 4.1) code + 5.1) context + 6.1) context + 7.1) bold + 7.2) context + 8.1) one + 9.1) two + 10.1) three + 11.1) six + 12.1) one + 13.1) two + 14.1) three + 15.1) six Contents (also called variable value) would be\: - 1.1) emphasize some text - 2.1) http://www.example.com/url with space/ - 3.1) Featureless Settings Specification - 4.1) const char *string = "My \"quoted\" C string."; - 5.1) is escaped to not be treated as EKI data - 6.1) bold - 7.1) bold - 8.1: important + 1.1) emphasize some text + 2.1) http://www.example.com/url with space/ + 3.1) Featureless Settings Specification + 4.1) const char *string = "My \"quoted\" C string."; + 5.1) bold + 6.1) bold + 7.1) important + 8.1) " escape + 9.1) \\ + 10.1) \" escape + 11.1) \\\\" escape + 12.1) \' escape + 13.1) \\' escape + 14.1) \\\' escape + 15.1) \\\\\\' escape The following are core specifications (each with a common name associated with the specification number)\: - eki-0000: Unrestricted diff --git a/specifications/fss-000c.txt b/specifications/fss-000c.txt index 8180e61..a85d1b3 100644 --- a/specifications/fss-000c.txt +++ b/specifications/fss-000c.txt @@ -1,7 +1,7 @@ # fss-0002 iki-0000 # # license open-standard-license-1.0-or-later -# version 2023/07/14 +# version 2023/11/19 # # This file (assumed to be named fss-000c.txt) can be more easily read using the following iki_read commands: # iki_read fss-000c.txt +Q -w -r FSS FSS -WWW character "'" "'" code '"' '"' italic '"' '"' @@ -13,18 +13,32 @@ Featureless Settings Specification: 000C - IKI Text: The IKI specifications are separate specifications from the FSS:"Featureless Settings Specifications". This is simply a more formal way to designate that this format utilizes IKI syntax. + This may also be used to designate EKI syntax. + + When neither an IKI nor an EKI header is specified and (other than code:"fss-000c" is specified) and the syntax is not known through some other means, then this can be assumed to be in IKI syntax rather than EKI syntax. The IKI syntax may be used in any FSS:"Featureless Settings Specifications". - The IKI format may be added to the. See the file:"iki.txt" specification for details on the IKI specifications. + See the file:"eki.txt" specification for details on the EKI specifications. + Example\: # fss-000c iki-0000 - This is a italic:"formal example" utilizing the FSS headers. + This is a italic:"formal example" utilizing the FSS and IKI headers. Example\: # iki-0000 - This is a italic:"informal example" utilizing the IKI headers. + This is a italic:"informal example" utilizing only the IKI headers. + + Example\: + # fss-000c eki-0000 + + This is a bold:italic:"informal example" utilizing the FSS and EKI headers. + + Example\: + # fss-000c + + This is a italic:"formal example" utilizing only the FSS headers, which in this case is treated as IKI rather than EKI. diff --git a/specifications/iki.txt b/specifications/iki.txt index be9ad89..884d6bf 100644 --- a/specifications/iki.txt +++ b/specifications/iki.txt @@ -1,7 +1,7 @@ # fss-0002 iki-0000 # # license open-standard-license-1.0-or-later -# version 2024/11/10 +# version 2024/11/19 # # This file (assumed to be named iki.txt) can be more easily read using the following iki_read commands: # iki_read iki.txt +Q -w -WWW character "'" "'" code '"' '"' italic '"' '"' @@ -13,37 +13,50 @@ 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 value 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 italic:"Object" and is also considered the vocabulary. - The variable value is considered the italic:"Content". - The variable name may be wrapped by a single open bracket, character:"[" (unicode:"U+005B"), at the start and a single close bracket, character:"]" (unicode:"U+005D"), at the end. + The IKI syntax describes a italic:"Variable" that is defined by a italic:"Vocabulary" name followed by quoted value called the italic:"Content". - The wrapping characters characters are not part of the variable name and must not be contained within a variable name. + The italic:"Variable" refers to the italic:"Vocabulary", italic:"Content", and associated syntax that describes the italic:"Variable". + The italic:"Variable" name may be wrapped by a single open bracket, character:"[" (unicode:"U+005B"), at the start and a single close bracket, character:"]" (unicode:"U+005D"), at the end. + The open and close brackets, also called the wrapping characters, for the italic:"Variable" do not utilize escaping characters and instead any escaping is perform against the colon character:":" (unicode:"U+003A") that separates the italic:"Vocabulary" from the italic:"Content". + The italic:"Vocabulary" generally defines the context and many of the IKI specifications may provide a discrete set of allowed italic:"Vocabulary". + The italic:"Vocabulary" may also be referred to as the italic:"Object". + The italic:"Vocabulary" only allows word characters or one of character:"_" (unicode:"U+005F"), character:"-" (unicode:"U+002D"), character:"+" (unicode:"U+002B"), character:"[" (unicode:"U+005B")). + White space, non-word, and non character:"_" (unicode:"U+005F"), character:"-" (unicode:"U+002D"), character:"+" (unicode:"U+002B")) character punctuation 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 (unicode:"U+2010" and unicode:"U+2011"). + Unicode punctuation connector characters are supported just like character:"_", except when they connect outside the current line (such as unicode:"U+FE33" character:"︳"). + The immediate left of a italic:"Vocabulary" must not be a valid italic:"Vocabulary" character, unless the italic:"Vocabulary" is wrapped using the wrapping characters. + Unicode invisible punctuation (such as invisible plus: unicode:"U+2064") are not considered a punctuation in this standard (because they a zero-width characters), therefore they are not to be considered a valid character:"_" (unicode:"U+005F"), character:"-" (unicode:"U+002D"), or character:"+" (unicode:"U+002B") Unicode equivalents. + + The wrapping characters characters are not part of the italic:"Vocabulary" name and instead only provide the syntax used to help identify a valid italic:"Variable". + The wrapping characters characters are part of the italic:"Variable". The wrapping characters do not support escaping. Both wrapping characters must be specified or neither. - The IKI format will use code:"iki-0000" to represent an IKI with no explicitly defined vocabulary. - Whereas code:"iki-0001" and beyond represent a specific IKI vocabulary. - - A potential IKI variable name starts on word character or one of character:"_" (unicode:"U+005F"), character:"-" (unicode:"U+002D"), character:"+" (unicode:"U+002B"), character:"[" (unicode:"U+005B")). - White space, non-word, and non character:"_" (unicode:"U+005F"), character:"-" (unicode:"U+002D"), character:"+" (unicode:"U+002B")) 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 (unicode:"U+2010" and unicode:"U+2011"). + The italic:"Content" refers to the value of the italic:"Variable". + The italic:"Content" is wrapped one of the following quote characters: single quote character:"'" (unicode:"U+0027"), double quote character:'"' (unicode:"U+0022"), or grave character:'`' (unicode:"U+0060"). + The italic:"Content" must escape any quotes that match the open and close quote used for the italic:"Variable" by utilizing a backslash character:"\\" (unicode:"U+005C"). + If a matching closing quote is not found until the end of the data (or file), then this unclosed italic:"Variable" is considered invalid. + The handling of this erroneous case is left to the implementation. - Any potential IKI data must be escaped to make it treated as non-IKI data by prepending a backslash character:"\\" before the colon character:":" that is before the opening quote (single, double, or grave (backtick)). Potential IKI data refers to any valid IKI sequence without considering the closing single quote character:"'" (unicode:"U+0027"), closing double quote character:'"' (unicode:"U+0022"), or closing grave character:'`' (unicode:"U+0060"). + The backslashes used for escaping quotes use character:"\\" (unicode:"U+005C"). + Unless otherwise specified, these backslash escapes are performed only when required and not unilaterally. + One backslash escapes the valid quote, resulting in the quote being part of the italic:"Content". + Two backslash escape the backslash, resulting in the backslash (but not the quote) being part of the italic:"Content". + Three backslash escapes or more escaped the quote and the first backslash. + Every backslash after the third is used literally and does no escape anything. - Unicode punctuation connector characters are supported just like character:"_", except when they connect outside the current line (such as unicode:"U+FE33" character:"︳"). - Unicode invisible punctuations (such as invisible plus: unicode:"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 character:"_", character:"-", or character:"+" Unicode equivalents. + The IKI format will use code:"iki-0000" to represent an IKI with no explicitly defined vocabulary. + Whereas code:"iki-0001" and beyond represent a specific IKI vocabulary. Key\: - code:"\o" = any printable word character, including character:"_", character:"-", character:"+" (and Unicode equivalents). - code:"\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. + code:"\o" = any printable word character, including character:"_" (unicode:"U+005F"), character:"-" (unicode:"U+002D"), character:"+" (unicode:"U+002B") (and Unicode equivalents). + code:"\c" = any character, including white space and non-printing, and any escaped quote (used as the opening quote) or a any quote (unescaped) not used as the opening quote. code:"\q" = either a single quote character:"'" (unicode:"U+0027"), a double quote character:'"' (unicode:"U+0022"), or a grave character:'`' (unicode:"U+0060"). code:"\x" = any character. - code:"\W" = any non-word character, discluding character:"_" (and Unicode equivalents), character:"-" (and Unicode equivalents), and character:"+" (and Unicode equivalents). + code:"\W" = any non-word character, discluding character:"_" (unicode:"U+005F") (and Unicode equivalents), character:"-" (unicode:"U+002D") (and Unicode equivalents), and character:"+" (unicode:"U+002B") (and Unicode equivalents). code:"\e" = an optional escape sequence of any number of backslashes, such as character:"\\" (unicode:"U+005C"). - code:"[" = a single conditionally optional open bracket, character:"[" (unicode:"U+005B"). - code:"]" = a single conditionally optional close bracket, character:"]" (unicode:"U+005D"). + code:"[" = a single (conditionally optional) open bracket, character:"[" (unicode:"U+005B"). + code:"]" = a single (conditionally optional) close bracket, character:"]" (unicode:"U+005D"). code:"*" = zero or more occurrences. code:"~" = one or more occurrences, or zero if at start of file. code:"+" = one or more occurrences. @@ -59,37 +72,55 @@ IKI Specifications: code:"" Example\: - code:'# fss-000c iki-0000 + code:`# fss-000c iki-0000 + + This is my sentence, anything can go here but sometimes I want to italic:"emphasize some text". + + Other times I want to render a URL such as this example URL: url:'http://www.example.com/url with space/'. - This is my sentence, anything can go here but sometimes I want to italic\:"emphasize some text". + There are no comments, except for maybe the FSS:"Featureless Settings Specification" header (which would not resolve to any IKI syntax anyway). - Other times I want to render a url such as this example url: url\:\'http://www.example.com/url with space/\'. + Quotes may be included, such as: code:"const char *string = \"My \\\"quoted\\\" C string.\";". - There are no comments, except for maybe the FSS\:"Featureless Settings Specification" header (which would not resolve to any IKI syntax anyway). + The following italic\:"is escaped to not be treated as IKI Variable". - Quotes may be included, such as: code\:"const char *string = \"My \\\"quoted\\\" C string.\";". + The conditionally optional open and close brackets allow for putting a variable directly next to another word character like: [context]:"bold"this[context]:"bold". - The following italic\:"is escaped to not be treated as IKI data". + These are examples of escapes: one:"\" escape", two:"\\" escape", three:"\\\" escape", six:"\\\\\\" escape". - The conditionally optional open and close brackets allow for putting a variable directly next to another word character like: [context]\:"bold"this[context]\:"bold".' + These are examples of non-escapes: one:"\' escape", two:"\\' escape", three:"\\\' escape", six:"\\\\\\' escape".` Objects (also called vocabulary or variable name) would be\: - 1) italic - 2) url - 3) FSS - 4) code - 5) italic - 6) context - 7) context + 1.1) italic + 2.1) URL + 3.1) FSS + 4.1) code + 5.1) context + 6.1) context + 7.1) one + 8.1) two + 9.1) three + 10.1) six + 11.1) one + 12.1) two + 13.1) three + 14.1) six Contents (also called variable value) would be\: - 1.1) emphasize some text - 2.1) http://www.example.com/url with space/ - 3.1) Featureless Settings Specification - 4.1) const char *string = "My \"quoted\" C string."; - 5.1) is escaped to not be treated as IKI data - 6.1) bold - 7.1) bold + 1.1) emphasize some text + 2.1) http://www.example.com/url with space/ + 3.1) Featureless Settings Specification + 4.1) const char *string = "My \"quoted\" C string."; + 5.1) bold + 6.1) bold + 7.1) " escape + 8.1) \ + 9.1) \" escape + 10.1) \\\\" escape + 11.1) \' escape + 12.1) \\' escape + 13.1) \\\' escape + 14.1) \\\\\\' escape The following are core specifications (each with a common name associated with the specification number)\: - iki-0000: Unrestricted -- 1.8.3.1