~trs-80/ostrta-spec

56be7a905b5dbc06c5894819cd07aa727cecea29 — TRS-80 9 months ago 7916ac4
Several more small changes

README.org: Change one of Free Software links to F/LOSS link.

Specifications.org: Remove code quotes from control code symbols, as
they were appearing in table and not being rendered.  Remove bold
formatting from Timestamp-ID tokens for same reason.

Specifications.org: Remove Orgmode '::' from several broken cross-page
links in order to fix them.

Specifications.org: Remove reference to ostrta-id-8.
4 files changed, 44 insertions(+), 44 deletions(-)

M README.md
M README.org
M Specifications.md
M Specifications.org
M README.md => README.md +3 -3
@@ 34,10 34,10 @@ I have been developing and using many of these concepts (and additional ones bes

### Goals

-   To come up with some common set of useful, general, free and open standards, guidelines, and/or best practices that many different people can implement in whatever language(s) they prefer, such that we don't all have to keep re-inventing the same wheels over and over again each time all by ourselves.
-   To come up with some common set of useful, general, free and open, and easy to implement standards, guidelines, and/or best practices that many different people can implement in whatever language(s) they prefer, such that we don't all have to keep re-inventing the same wheels over and over again each time all by ourselves.
    -   To have a single, easy to point to place on the Internet where said information is all laid out (i.e., this page).  Or at least a place to focus discussion and further develop ideas.

-   The end goal being able to improve the ability to store and recall various sorts of information in a more useful, reliable, and/or convenient way.
-   The end goal being able to improve the ability to store and recall various sorts of information / data in a more useful, reliable, and/or convenient way.

One of many inspirations would be something like Vannevar Bush's Memex, but let's not get ahead of ourselves here.  Currently we are just trying to agree on some simple file naming conventions.  :D



@@ 62,7 62,7 @@ Examples of things meeting these criteria are:
-   standard file and folder based naming
-   email
-   free and open image and document formats
-   [Free Software](https://www.fsf.org/about/what-is-free-software) tools
-   [F/LOSS](https://www.gnu.org/philosophy/floss-and-foss.en.html) tools
-   etc.

### Timeline and ISO-like dates as Identifiers

M README.org => README.org +3 -3
@@ 35,11 35,11 @@ I have been developing and using many of these concepts (and additional ones bes
    :CUSTOM_ID:            goals
    :END:

- To come up with some common set of useful, general, free and open standards, guidelines, and/or best practices that many different people can implement in whatever language(s) they prefer, such that we don't all have to keep re-inventing the same wheels over and over again each time all by ourselves.
- To come up with some common set of useful, general, free and open, and easy to implement standards, guidelines, and/or best practices that many different people can implement in whatever language(s) they prefer, such that we don't all have to keep re-inventing the same wheels over and over again each time all by ourselves.

  - To have a single, easy to point to place on the Internet where said information is all laid out (i.e., this page).  Or at least a place to focus discussion and further develop ideas.

- The end goal being able to improve the ability to store and recall various sorts of information in a more useful, reliable, and/or convenient way.
- The end goal being able to improve the ability to store and recall various sorts of information / data in a more useful, reliable, and/or convenient way.

One of many inspirations would be something like Vannevar Bush's Memex, but let's not get ahead of ourselves here.  Currently we are just trying to agree on some simple file naming conventions.  :D



@@ 70,7 70,7 @@ Examples of things meeting these criteria are:
- standard file and folder based naming
- email
- free and open image and document formats
- [[https://www.fsf.org/about/what-is-free-software][Free Software]] tools
- [[https://www.gnu.org/philosophy/floss-and-foss.en.html][F/LOSS]] tools
- etc.

*** Timeline and ISO-like dates as Identifiers

M Specifications.md => Specifications.md +19 -19
@@ 11,13 11,13 @@

# Specifications

Here follow (in alphabetical order) some more detailed notes on implementing some of the [general concepts](README.md).
Here follow (in alphabetical order) some more detailed notes on implementing some of the [general concepts](README.org#general-concepts).

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED","MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).

## Controlled Vocabulary

For a conceptual overview, see the [Controlled Vocabulary](README.md) section in General Concepts.
For a conceptual overview, see the [Controlled Vocabulary](README.org#controlled-vocabulary) section in General Concepts.

1.  **CV item** is defined as a contiguous word or term used as an additional axis of metadata.  Commonly referred to as a "tag" but that is only one usage, so here we use the more general term.
    1.  By contiguous, we mean that spaces MUST NOT be used.


@@ 26,7 26,7 @@ For a conceptual overview, see the [Controlled Vocabulary](README.md) section in

### CV File Format

An implementation of the [concept](README.md) of including additional disambiguation notes directly in the same place you are choosing the CV item from, in a simple plain text file format.
An implementation of the [concept](README.org#disambiguation-notes-live-directly-with-cv-items) of including additional disambiguation notes directly in the same place you are choosing the CV item from, in a simple plain text file format.

Using common example of selecting tag(s), the plain text CV file implementation we propose looks like:



@@ 35,7 35,7 @@ Using common example of selecting tag(s), the plain text CV file implementation 
    tag3    use tag2 instead

1.  Where:
    1.  The CV item (i.e., "tag") MUST appear at the beginning of each line.
    1.  Each CV item (i.e., "tag") MUST appear at the beginning of each line.
    
    2.  CV items MUST be separated by newlines.
    


@@ 51,14 51,14 @@ Using common example of selecting tag(s), the plain text CV file implementation 

## Data File

For tabular data meeting the following criteria:
For storage of tabular data meeting the following criteria:

1.  multiple fields / columns
2.  more complicated than what is possible with a [CV file](#cv-file-format)
3.  not nested (more than a few levels)
4.  nor otherwise complicated enough to require JSON
4.  nor otherwise complicated enough to require something like JSON

&#x2026;we propose a simple yet dramatic improvement to the common CSV file, a return to using basic ASCII control codes which were expressly designed for the purpose, and have none of the (mostly quote related) parsing and escaping issues of CSV files.<sup><a id="fnr.1" class="footref" href="#fn.1">1</a></sup>
&#x2026;we propose a simple yet dramatic improvement to the common CSV file, a return to using basic ASCII control codes which were expressly designed for the purpose, and have none of the parsing and escaping issues of CSV files.<sup><a id="fnr.1" class="footref" href="#fn.1">1</a></sup>

<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">



@@ 86,7 86,7 @@ For tabular data meeting the following criteria:

<tbody>
<tr>
<td class="org-left">`^\`</td>
<td class="org-left">^\\</td>
<td class="org-right">28</td>
<td class="org-left">1C</td>
<td class="org-left">FS</td>


@@ 95,7 95,7 @@ For tabular data meeting the following criteria:


<tr>
<td class="org-left">`^]`</td>
<td class="org-left">^]</td>
<td class="org-right">29</td>
<td class="org-left">1D</td>
<td class="org-left">GS</td>


@@ 104,7 104,7 @@ For tabular data meeting the following criteria:


<tr>
<td class="org-left">`^^`</td>
<td class="org-left">^^</td>
<td class="org-right">30</td>
<td class="org-left">1E</td>
<td class="org-left">RS</td>


@@ 113,7 113,7 @@ For tabular data meeting the following criteria:


<tr>
<td class="org-left">`^_`</td>
<td class="org-left">^\_</td>
<td class="org-right">31</td>
<td class="org-left">1F</td>
<td class="org-left">US</td>


@@ 156,7 156,7 @@ A much more detailed definition:

    timestamp-id [_description...] [--[tag...]-another_tag...] [.ext]

1.  **timestamp-id** is the only strictly required part and therefore MUST follow ostrta-id-4 (at minimum) but MAY achieve higher resolution by following ostrta-id-6, ostrta-id-8, etc.  See the [timestamp-ID](#timestamp-id) specification for further detail.
1.  **timestamp-id** is the only strictly required part and therefore MUST follow ostrta-id-4 (at minimum) but MAY achieve higher resolution by following ostrta-id-6, etc.  See the [timestamp-ID](#timestamp-id) specification for further detail.

2.  **description** is OPTIONAL but if present MUST start with an underscore (`_`) delimiter to clearly mark its separation from the timestamp.
    1.  The initial delimiter (`_`) is not considered a part of the description.  It is a delimiter.


@@ 190,7 190,7 @@ A much more detailed definition:
    
    3.  The intention of this rule is to insure the timestamp-id portion of the filename remains a reliable identifier.

Alternatively, you MAY leave the base timestamp-id there by itself (perhaps only along with the extension) and implement your metadata in another index file or even a database (although plain text files are always [preferred](README.md)).<sup><a id="fnr.3" class="footref" href="#fn.3">3</a></sup>
Alternatively, you MAY leave the base timestamp-id there by itself (perhaps only along with the extension) and implement your metadata in a separate [data file](#data-file) or even a database (although plain text files are always [preferred](README.org#relying-strictly-on-floss-and-lowest-common-denominator-formats).<sup><a id="fnr.3" class="footref" href="#fn.3">3</a></sup>

## Filesystem



@@ 258,7 258,7 @@ The Timestamp-ID specification is a very simple "ISO-like" timestamp:

<tbody>
<tr>
<td class="org-left">**YYYY**</td>
<td class="org-left">YYYY</td>
<td class="org-left">the year</td>
<td class="org-left">4 digit</td>
<td class="org-left">MUST</td>


@@ 266,7 266,7 @@ The Timestamp-ID specification is a very simple "ISO-like" timestamp:


<tr>
<td class="org-left">**MM**</td>
<td class="org-left">MM</td>
<td class="org-left">the month</td>
<td class="org-left">zero padded</td>
<td class="org-left">MUST</td>


@@ 274,7 274,7 @@ The Timestamp-ID specification is a very simple "ISO-like" timestamp:


<tr>
<td class="org-left">**DD**</td>
<td class="org-left">DD</td>
<td class="org-left">the day</td>
<td class="org-left">zero padded</td>
<td class="org-left">MUST</td>


@@ 282,7 282,7 @@ The Timestamp-ID specification is a very simple "ISO-like" timestamp:


<tr>
<td class="org-left">**HH**</td>
<td class="org-left">HH</td>
<td class="org-left">the hour</td>
<td class="org-left">24 hour</td>
<td class="org-left">MUST</td>


@@ 290,7 290,7 @@ The Timestamp-ID specification is a very simple "ISO-like" timestamp:


<tr>
<td class="org-left">**MM**</td>
<td class="org-left">MM</td>
<td class="org-left">the minute</td>
<td class="org-left">zero padded</td>
<td class="org-left">MUST</td>


@@ 298,7 298,7 @@ The Timestamp-ID specification is a very simple "ISO-like" timestamp:


<tr>
<td class="org-left">**SS**</td>
<td class="org-left">SS</td>
<td class="org-left">the second</td>
<td class="org-left">zero padded</td>
<td class="org-left">OPTIONAL</td>

M Specifications.org => Specifications.org +19 -19
@@ 3,7 3,7 @@
  :CUSTOM_ID:            specifications
  :END:

Here follow (in alphabetical order) some more detailed notes on implementing some of the [[file:README.org::#general-concepts][general concepts]].
Here follow (in alphabetical order) some more detailed notes on implementing some of the [[file:README.org#general-concepts][general concepts]].

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED","MAY", and "OPTIONAL" in this document are to be interpreted as described in [[https://tools.ietf.org/html/rfc2119][RFC 2119]].



@@ 12,7 12,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
   :CUSTOM_ID:            controlled-vocabulary
   :END:

For a conceptual overview, see the [[file:README.org::#controlled-vocabulary][Controlled Vocabulary]] section in General Concepts.
For a conceptual overview, see the [[file:README.org#controlled-vocabulary][Controlled Vocabulary]] section in General Concepts.

1. *CV item* is defined as a contiguous word or term used as an additional axis of metadata.  Commonly referred to as a "tag" but that is only one usage, so here we use the more general term.



@@ 25,7 25,7 @@ For a conceptual overview, see the [[file:README.org::#controlled-vocabulary][Co
    :CUSTOM_ID:            cv-file-format
    :END:

An implementation of the [[file:README.org::#disambiguation-notes-live-directly-with-cv-items][concept]] of including additional disambiguation notes directly in the same place you are choosing the CV item from, in a simple plain text file format.
An implementation of the [[file:README.org#disambiguation-notes-live-directly-with-cv-items][concept]] of including additional disambiguation notes directly in the same place you are choosing the CV item from, in a simple plain text file format.

Using common example of selecting tag(s), the plain text CV file implementation we propose looks like:



@@ 37,7 37,7 @@ Using common example of selecting tag(s), the plain text CV file implementation 

1. Where:

   1. The CV item (i.e., "tag") MUST appear at the beginning of each line.
   1. Each CV item (i.e., "tag") MUST appear at the beginning of each line.

   2. CV items MUST be separated by newlines.



@@ 58,22 58,22 @@ Using common example of selecting tag(s), the plain text CV file implementation 
   :CUSTOM_ID:            data-file
   :END:

For tabular data meeting the following criteria:
For storage of tabular data meeting the following criteria:

1. multiple fields / columns
2. more complicated than what is possible with a [[#cv-file-format][CV file]]
3. not nested (more than a few levels)
4. nor otherwise complicated enough to require JSON
4. nor otherwise complicated enough to require something like JSON

...we propose a simple yet dramatic improvement to the common CSV file, a return to using basic ASCII control codes which were expressly designed for the purpose, and have none of the (mostly quote related) parsing and escaping issues of CSV files.[fn:1]
...we propose a simple yet dramatic improvement to the common CSV file, a return to using basic ASCII control codes which were expressly designed for the purpose, and have none of the parsing and escaping issues of CSV files.[fn:1]

|-----+-----+-----+--------+------------------|
| Seq | Dec | Hex | Abbrev | Name             |
|-----+-----+-----+--------+------------------|
| =^\=  |  28 | 1C  | FS     | File Separator   |
| =^]=  |  29 | 1D  | GS     | Group Separator  |
| =^^=  |  30 | 1E  | RS     | Record Separator |
| =^_=  |  31 | 1F  | US     | Unit Separator   |
| ^\  |  28 | 1C  | FS     | File Separator   |
| ^]  |  29 | 1D  | GS     | Group Separator  |
| ^^  |  30 | 1E  | RS     | Record Separator |
| ^_  |  31 | 1F  | US     | Unit Separator   |
|-----+-----+-----+--------+------------------|

Above table and below quote are from Wikipedia article [[https://en.wikipedia.org/wiki/C0_and_C1_control_codes#Field_separators][C0 and C1 control codes]].[fn:2]


@@ 127,7 127,7 @@ A much more detailed definition:
  timestamp-id [_description...] [--[tag...]-another_tag...] [.ext]
#+end_example

1. *timestamp-id* is the only strictly required part and therefore MUST follow ostrta-id-4 (at minimum) but MAY achieve higher resolution by following ostrta-id-6, ostrta-id-8, etc.  See the [[#timestamp-id][timestamp-ID]] specification for further detail.
1. *timestamp-id* is the only strictly required part and therefore MUST follow ostrta-id-4 (at minimum) but MAY achieve higher resolution by following ostrta-id-6, etc.  See the [[#timestamp-id][timestamp-ID]] specification for further detail.

2. *description* is OPTIONAL but if present MUST start with an underscore (=_=) delimiter to clearly mark its separation from the timestamp.



@@ 167,7 167,7 @@ A much more detailed definition:

   3. The intention of this rule is to insure the timestamp-id portion of the filename remains a reliable identifier.

Alternatively, you MAY leave the base timestamp-id there by itself (perhaps only along with the extension) and implement your metadata in another index file or even a database (although plain text files are always [[file:README.org::#relying-strictly-on-floss-and-lowest-common-denominator-formats][preferred]]).[fn:3]
Alternatively, you MAY leave the base timestamp-id there by itself (perhaps only along with the extension) and implement your metadata in a separate [[#data-file][data file]] or even a database (although plain text files are always [[file:README.org#relying-strictly-on-floss-and-lowest-common-denominator-formats][preferred]].[fn:3]

** Filesystem
   :PROPERTIES:


@@ 225,12 225,12 @@ The Timestamp-ID specification is a very simple "ISO-like" timestamp:
|-------+------------+-------------+-----------|
| Token | Value      | Format      | Required? |
|-------+------------+-------------+-----------|
| *YYYY*  | the year   | 4 digit     | MUST      |
| *MM*    | the month  | zero padded | MUST      |
| *DD*    | the day    | zero padded | MUST      |
| *HH*    | the hour   | 24 hour     | MUST      |
| *MM*    | the minute | zero padded | MUST      |
| *SS*    | the second | zero padded | OPTIONAL  |
| YYYY  | the year   | 4 digit     | MUST      |
| MM    | the month  | zero padded | MUST      |
| DD    | the day    | zero padded | MUST      |
| HH    | the hour   | 24 hour     | MUST      |
| MM    | the minute | zero padded | MUST      |
| SS    | the second | zero padded | OPTIONAL  |
|-------+------------+-------------+-----------|

Time resolution smaller than one second MAY be defined, but so far there has been no need and thus no discussion what that might look like.