~trs-80/ostrta-spec

9cbc7b3fecd92a5d3c6de7dd0f2655bcfcc20eac — TRS-80 9 months ago c2cf1cb
Change lists from - to numbers

Probably some other small edits also.
2 files changed, 75 insertions(+), 72 deletions(-)

M Specifications.md
M Specifications.org
M Specifications.md => Specifications.md +37 -36
@@ 9,7 9,7 @@
        2.  [Full Filename Specification](#full-filename-specification)
    3.  [Filesystem](#filesystem)
    4.  [Timestamp-ID](#timestamp-id)
        1.  [ostrta-id-N](#ostrta-id-N)
        1.  [ostrta-id-N](#ostrta-id-n)

# Specifications



@@ 21,10 21,10 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S

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

-   **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.
    -   By contiguous, we mean that spaces MUST NOT be used.
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.
    
    -   Under<sub>scores</sub>, camelCase, PascalCase, etc. MAY be used instead within CV items.
    2.  Under<sub>scores</sub>, camelCase, PascalCase, etc. MAY be used instead within CV items.

### CV File Format



@@ 36,20 36,20 @@ Using common example of selecting tag(s), the plain text CV file implementation 
    tag2    <- tag3
    tag3    use tag2 instead

-   Where:
    -   The CV item (i.e., "tag") MUST appear at the beginning of each line.
1.  Where:
    1.  The CV item (i.e., "tag") MUST appear at the beginning of each line.
    
    -   CV items MUST be separated by newlines.
    2.  CV items MUST be separated by newlines.
    
    -   CV item MAY be followed by OPTIONAL disambiguation notes.  If notes follow, they MUST be separated from CV item by at least one space character.
        -   This makes discarding the disambiguation notes from the desired tag (after selection) trivial in many different programming languages.
    3.  CV item MAY be followed by OPTIONAL disambiguation notes.  If notes follow, they MUST be separated from CV item by at least one space character.
        1.  This makes discarding the disambiguation notes from the desired tag (after selection) trivial in many different programming languages.
    
    -   Redirection from one CV item to another MAY be accomplished by way of simple arrow glyph of "less than and hyphen" (`<-`).
    4.  Redirection from one CV item to another MAY be accomplished by way of simple arrow glyph of "less than and hyphen" (`<-`).
    
    -   Other than above extremely simple requirements, you are not only free but actually encouraged to use whatever terms, glyphs, etc. make sense *to you personally*.
    5.  Other than above extremely simple requirements, you are not only free but actually encouraged to use whatever terms, glyphs, etc. make sense *to you personally*.

-   In addition to the above:
    -   Implementations SHOULD provide a user selectable option whether to limit selections strictly to the choices in CV file, or allow adding new items "on the fly."
2.  In addition to the above:
    1.  Implementations SHOULD provide a user selectable option whether to limit selections strictly to the choices in CV file, or allow adding new items "on the fly."

## Filename



@@ 57,7 57,7 @@ The filename spec is based upon (and closely related to) the [timestamp-ID](#tim

### Minimum

The minimum file name considered to be following the spec would be a simple [ostrta-id-4](#ostrta-id-N) with no extension:
The minimum file name considered to be following the spec would be a simple [ostrta-id-4](#ostrta-id-n) with no extension:

    YYYY-MM-DD-HHMM



@@ 73,40 73,41 @@ A much more detailed definition:

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

-   **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, ostrta-id-8, etc.  See the [timestamp-ID](#timestamp-id) specification for further detail.

-   **description** is OPTIONAL but if present MUST start with an underscore (`_`) delimiter to clearly mark its separation from the timestamp.
    -   The initial delimiter (`_`) is not considered a part of the description.  It is a delimiter.
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.
    
    -   Illegal characters throughout the file name depend on the file system.  Having said that, I think the project SHOULD endeavour to develop a short list which any implementation SHOULD check against when implementing any sort of (re-)naming function(s).
        -   exFAT (common on larger SD cards) for example does not allow {`/\:*?\"<>|`}
    2.  Illegal characters throughout the file name depend on the file system.  Having said that, I think the project SHOULD endeavour to develop a short list which any implementation SHOULD check against when implementing any sort of (re-)naming function(s).
        1.  exFAT (common on larger SD cards) for example does not allow {`/\:*?\"<>|`}
    
    -   Besides the above, I think we SHOULD NOT use spaces (personally I use underscores instead) but I guess that does not have to be part of spec.
    3.  Besides the above, I think we SHOULD NOT use spaces (personally I use underscores instead) but I guess that does not have to be part of spec.
    
    -   Note that periods (`.`) MAY be present in description.  N.B. how we define filename extension (.ext) below!
    4.  Note that periods (`.`) MAY be present in description.  N.B. how we define filename extension (.ext) below!

-   **tags** are also OPTIONAL but if present must start with double hyphen (`--`) delimiter to clearly separate them from the description.
    -   The initial delimiter (`--`) SHALL NOT be considered a part of any tags.  It is a delimiter.
3.  **tags** are also OPTIONAL but if present must start with double hyphen (`--`) delimiter to clearly separate them from the description.
    1.  The initial delimiter (`--`) SHALL NOT be considered a part of any tags.  It is a delimiter.
    
    -   Within tags, there MAY be spaces, but again, underscores SHOULD be used instead.
    2.  Within tags, there MAY be spaces, but again, underscores SHOULD be used instead.
    
    -   Different tags MUST be separated with hyphens (`-`).
    3.  Different tags MUST be separated by a hyphen (`-`) as delimiter.
        1.  Corollary to this, individual tags MUST NOT contain hyphens (`-`).
    
    -   Note that periods (`.`) MAY be present in tags.  N.B. how we define filename extension (.ext) below!
    4.  Note that periods (`.`) MAY be present in tags.  N.B. how we define filename extension (.ext) below!

-   We define filename extension (**.ext**) as the last group of legal characters (including letters, numbers, symbols) at the end of the file name after the last period (`.`).
    -   This means that extensions MAY be arbitrary length.  I get a headache just thinking about the potential implications here, so I would welcome feedback from anyone who has more experience dealing with something like this.  In particular I wonder if we should limit it to some number of characters.
4.  We define filename extension (**.ext**) as the last group of legal characters (including letters, numbers, symbols) at the end of the file name after the last period (`.`).
    1.  This means that extensions MAY be arbitrary length.  I get a headache just thinking about the potential implications here, so I would welcome feedback from anyone who has more experience dealing with something like this.  In particular I wonder if we should limit it to some number of characters.
    
    -   At the moment nothing really relies on this anyway, but some day it might, hence me trying to come up with a good definition here.
    2.  At the moment nothing really relies on this anyway, but some day it might, hence me trying to come up with a good definition here.

-   Editing filename after initial creation or processing:
    -   The optional parts of file name (description, tags, etc.) MAY (and *should)* change!
5.  Editing filename after initial creation or processing:
    1.  The optional parts of file name (description, tags, etc.) MAY (and *should)* change!
    
    -   The timestamp-id portion MUST never change (after initial assignment / processing).
    2.  The timestamp-id portion MUST never change (after initial assignment / processing).
    
    -   The intention of this rule is to insure the timestamp-id portion of the filename remains a reliable identifier.
    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 preferred).<sup><a id="fnr.1" class="footref" href="#fn.1">1</a></sup>
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.1" class="footref" href="#fn.1">1</a></sup>

## Filesystem



@@ 145,7 146,7 @@ One thing in particular I noticed so far is that having the intermediate month f

## Timestamp-ID

Related closely to the base Filename spec, and vice-versa.
Related closely to the base [filename](#filename) spec, and vice-versa.

### ostrta-id-N



@@ 192,7 193,7 @@ The notion of `-4` and `-6` comes from the size of the last group of digits in t

Therefore it is an expression of the level of time resolution (minute and second, respectively).

I suppose there MAY be `-8` (or further) but I personally have not come across the need as of yet.
I suppose there MAY eventually be `-8` (or further) but I personally have not come across the need as of yet.

-   Then we would also need to get into discussion of whether to use period, etc. for fractional seconds or what.  So I suppose we cross that bridge when we come to it.


M Specifications.org => Specifications.org +38 -36
@@ 14,11 14,11 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S

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

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

  - By contiguous, we mean that spaces MUST NOT be used.
   1. By contiguous, we mean that spaces MUST NOT be used.

  - Under_scores, camelCase, PascalCase, etc. MAY be used instead within CV items.
   2. Under_scores, camelCase, PascalCase, etc. MAY be used instead within CV items.

*** CV File Format
    :PROPERTIES:


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

- Where:
1. Where:

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

  - CV items MUST be separated by newlines.
   2. CV items MUST be separated by newlines.

  - CV item MAY be followed by OPTIONAL disambiguation notes.  If notes follow, they MUST be separated from CV item by at least one space character.
   3. CV item MAY be followed by OPTIONAL disambiguation notes.  If notes follow, they MUST be separated from CV item by at least one space character.

    - This makes discarding the disambiguation notes from the desired tag (after selection) trivial in many different programming languages.
      1. This makes discarding the disambiguation notes from the desired tag (after selection) trivial in many different programming languages.

  - Redirection from one CV item to another MAY be accomplished by way of simple arrow glyph of "less than and hyphen" (=<-=).
   4. Redirection from one CV item to another MAY be accomplished by way of simple arrow glyph of "less than and hyphen" (=<-=).

  - Other than above extremely simple requirements, you are not only free but actually encouraged to use whatever terms, glyphs, etc. make sense /to you personally/.
   5. Other than above extremely simple requirements, you are not only free but actually encouraged to use whatever terms, glyphs, etc. make sense /to you personally/.

- In addition to the above:
2. In addition to the above:

  - Implementations SHOULD provide a user selectable option whether to limit selections strictly to the choices in CV file, or allow adding new items "on the fly."
   1. Implementations SHOULD provide a user selectable option whether to limit selections strictly to the choices in CV file, or allow adding new items "on the fly."

** Filename
   :PROPERTIES:


@@ 65,7 65,7 @@ The filename spec is based upon (and closely related to) the [[#timestamp-id][ti
    :CUSTOM_ID:            minimum
    :END:

The minimum file name considered to be following the spec would be a simple [[#ostrta-id-N][ostrta-id-4]] with no extension:
The minimum file name considered to be following the spec would be a simple [[#ostrta-id-n][ostrta-id-4]] with no extension:

#+begin_example
  YYYY-MM-DD-HHMM


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

- *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, ostrta-id-8, etc.  See the [[#timestamp-id][timestamp-ID]] specification for further detail.

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

  - The initial delimiter (=_=) is not considered a part of the description.  It is a delimiter.
   1. The initial delimiter (=_=) is not considered a part of the description.  It is a delimiter.

  - Illegal characters throughout the file name depend on the file system.  Having said that, I think the project SHOULD endeavour to develop a short list which any implementation SHOULD check against when implementing any sort of (re-)naming function(s).
   2. Illegal characters throughout the file name depend on the file system.  Having said that, I think the project SHOULD endeavour to develop a short list which any implementation SHOULD check against when implementing any sort of (re-)naming function(s).

    - exFAT (common on larger SD cards) for example does not allow {=/\:*?\"<>|=}
      1. exFAT (common on larger SD cards) for example does not allow {=/\:*?\"<>|=}

  - Besides the above, I think we SHOULD NOT use spaces (personally I use underscores instead) but I guess that does not have to be part of spec.
   3. Besides the above, I think we SHOULD NOT use spaces (personally I use underscores instead) but I guess that does not have to be part of spec.

  - Note that periods (=.=) MAY be present in description.  N.B. how we define filename extension (.ext) below!
   4. Note that periods (=.=) MAY be present in description.  N.B. how we define filename extension (.ext) below!

- *tags* are also OPTIONAL but if present must start with double hyphen (=--=) delimiter to clearly separate them from the description.
3. *tags* are also OPTIONAL but if present must start with double hyphen (=--=) delimiter to clearly separate them from the description.

  - The initial delimiter (=--=) SHALL NOT be considered a part of any tags.  It is a delimiter.
   1. The initial delimiter (=--=) SHALL NOT be considered a part of any tags.  It is a delimiter.

  - Within tags, there MAY be spaces, but again, underscores SHOULD be used instead.
   2. Within tags, there MAY be spaces, but again, underscores SHOULD be used instead.

  - Different tags MUST be separated with hyphens (=-=).
   3. Different tags MUST be separated by a hyphen (=-=) as delimiter.

  - Note that periods (=.=) MAY be present in tags.  N.B. how we define filename extension (.ext) below!
      1. Corollary to this, individual tags MUST NOT contain hyphens (=-=).

- We define filename extension (*.ext*) as the last group of legal characters (including letters, numbers, symbols) at the end of the file name after the last period (=.=).
   4. Note that periods (=.=) MAY be present in tags.  N.B. how we define filename extension (.ext) below!

  - This means that extensions MAY be arbitrary length.  I get a headache just thinking about the potential implications here, so I would welcome feedback from anyone who has more experience dealing with something like this.  In particular I wonder if we should limit it to some number of characters.
4. We define filename extension (*.ext*) as the last group of legal characters (including letters, numbers, symbols) at the end of the file name after the last period (=.=).

  - At the moment nothing really relies on this anyway, but some day it might, hence me trying to come up with a good definition here.
   1. This means that extensions MAY be arbitrary length.  I get a headache just thinking about the potential implications here, so I would welcome feedback from anyone who has more experience dealing with something like this.  In particular I wonder if we should limit it to some number of characters.

- Editing filename after initial creation or processing:
   2. At the moment nothing really relies on this anyway, but some day it might, hence me trying to come up with a good definition here.

  - The optional parts of file name (description, tags, etc.) MAY (and /should)/ change!
5. Editing filename after initial creation or processing:

  - The timestamp-id portion MUST never change (after initial assignment / processing).
   1. The optional parts of file name (description, tags, etc.) MAY (and /should)/ change!

  - The intention of this rule is to insure the timestamp-id portion of the filename remains a reliable identifier.
   2. The timestamp-id portion MUST never change (after initial assignment / processing).

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 preferred).[fn:1]
   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:1]

** Filesystem
   :PROPERTIES:


@@ 175,11 177,11 @@ One thing in particular I noticed so far is that having the intermediate month f
   :CUSTOM_ID:            timestamp-id
   :END:

Related closely to the base Filename spec, and vice-versa.
Related closely to the base [[#filename][filename]] spec, and vice-versa.

*** ostrta-id-N
    :PROPERTIES:
    :CUSTOM_ID:            ostrta-id-N
    :CUSTOM_ID:            ostrta-id-n
    :END:

The notion of =-4= and =-6= comes from the size of the last group of digits in the timestamp:


@@ 194,7 196,7 @@ The notion of =-4= and =-6= comes from the size of the last group of digits in t

Therefore it is an expression of the level of time resolution (minute and second, respectively).

I suppose there MAY be =-8= (or further) but I personally have not come across the need as of yet.
I suppose there MAY eventually be =-8= (or further) but I personally have not come across the need as of yet.

- Then we would also need to get into discussion of whether to use period, etc. for fractional seconds or what.  So I suppose we cross that bridge when we come to it.