Data Asset Manifest

'("shaggy-dog-tale"
  ("versions"
   ("current"
    ("sourcehut"
     ("location" . "https://example.org/shaggy-dog-tale/")
     ("formats" . ("html"))))))

(setq dam-channels
      '(("emsenn"
         ("brutstrap-css"
          ("name" . "Brutstrap CSS")
          ("description" . "a cascading stylesheet for representing HTML content as it is constructed.")
          ("creator" . "emsenn")
          ("license" . "CC0")
          ("versions"
           ("current"
            ("sourcehut"
             ("location" . "https://git.sr.ht/~emsenn/brutstrap-css/blob/master/")
             ("formats" . ("html" "md" "pdf" "tex" "txt")))))))))

(setq dam-channels
      '(("emsenn"
         ("brutstrap-css"
          ("name" . "Brutstrap CSS")
          ("description" . "a cascading stylesheet for representing HTML content as it is constructed.")
          ("creator" . "emsenn")
          ("license" . "CC0")
          ("versions"
           ("current"
            ("sourcehut"
             ("location" . "https://git.sr.ht/~emsenn/brutstrap-css/blob/master/")
             ("formats" . ("html" "md" "pdf" "tex" "txt")))))))))
(defun dam-get-channels
    ()
    (loop for channel
          in dam-channels
          collect (car channel)))
(defun dam-get-channel
    (channel)
  (cdr (assoc channel dam-channels)))
(defun dam-get-manifests
    (channel)
  "Return a list of the manifests recorded in CHANNEL."
  (loop for manifest
        in (dam-get-channel channel)
        collect (car manifest)))
(defun dam-get-manifest
    (channel id)
  "Return manifest ID from CHANNEL."
  (assoc id (dam-get-channel channel)))
(defun dam-get-versions
    (channel id)
  "Get the declared versions of ID from CHANNEL."
  (loop for versions
        in (cdr
            (assoc "versions"
                   (dam-get-manifest channel id)))
        collect (car versions)))
(defun dam-get-version
    (channel id version)
  "Return VERSION of ID from CHANNEL."
  (cdr (assoc version (cdr (assoc "versions" (dam-get-manifest channel id))))))
(defun dam-get-sources
    (channel id version)
  "Return a list of sources for VERSION of ID."
  (loop for source
        in (dam-get-version channel id version)
        collect (car source)))
(defun dam-get-source
    (channel id version source)
  "Return SOURCE for VERSION of ID."
  (cdr (assoc source (dam-get-version channel id version))))
(defun dam-get-location
    (channel id version source)
  "Return the location for VERSION of ID at SOURCE."
  (cdr (assoc "location" (dam-get-source channel id version source)))
  )
(defun dam-get-formats
    (channel id version source)
  "Return the available formats for VERSION of ID at SOURCE from
  CHANNEL."
  (cdr (assoc "formats" (dam-get-source channel id version source))))
(defun dam-get-path
    (channel id version source format)
  "Return a url for the VERSION of ID at SOURCE from CHANNEL in FORMAT."
  (concat
   (dam-get-location channel id version source)
   id
   "."
   format))
(defun dam-open-asset
    (channel id version source format)
  "Open VERSION of ID from SOURCE from CHANNEL in FORMAT."
  (interactive "schannel: \nsid: \nsversion: \nssource: \nsformat :")
  (browse-url
   (dam-get-path
    channel id
    version source format)))

#+title: Data Asset Manifest
#+export_file_name: ./data-asset-manifest
#+options: prop:("version-added" "version-changed") todo:t
#+html_head: <link rel="stylesheet" type="text/css" href="../brutstrap-css/brutstrap.css">
#+macro: document-type proposal
#+toc: headlines 7 :only-contents t
* Introduction
  :PROPERTIES:
  :CUSTOM_ID: introduction
  :END:
{{{document-is-prototype(specification)}}}

This {{{doc}}} contains the specification for a /data asset manifest/
and /data asset manifest channel/, formats for maintaining a record
about a piece of (implicitly digital) content and a listing of those
records.

{{{document-eli(default)}}}
* Data Asset Manifest
  :PROPERTIES:
  :header-args: :results value silence :eval no-export :noweb yes :tangle ./dam.el :padline no
  :END:
** Overview

A /data asset manifest/ is a record of /declarations/ about a /data
asset/, an (implicitly digital) resource such as an essay or
illustration.[fn:1] The record, or /manifest/, includes at least information
about available /versions/ and /sources/ of the /asset/, and may
include information about its /title/, /creator/, /license/, and more.

#+name: manifest-example
#+begin_src elisp :eval no :tangle nil
  '("shaggy-dog-tale"
    ("versions"
     ("current"
      ("sourcehut"
       ("location" . "https://example.org/shaggy-dog-tale/")
       ("formats" . ("html"))))))
#+end_src

This example includes all of the /manifest's/ required elements, and
nothing else. The /identifier/ of the /data asset/ is
=shaggy-dog-tale=, it has a single version called =current= available,
whcih is available at a single source, =sourcehut=, which stores the
/asset/ at =https://emsenn.org/shaggy-dog/tale/= in a single format,
=html=.

A /data asset manifest channel/ is a list of /manifests/ without
duplicate /identifiers/.

A note on convention. Many variables (including function names) will
be prefixed with =dam-=. This an initialism of /data asset manifest/,
and its use as a prefix is a convention in /Emacs Lisp/ to avoid
contaminating the general namespace.

To see all code implemented below in a single file, see the included
[[file:./dam.el][=dam.el=]] file or the [[#all-code]["All Code"]] section of the [[#supplements]["Supplements"]].
** Data Asset Manifest Structure
- Version added :: 0.1.0
This section explains all recognized elements of a /data asset
manifest/.
*** DRAFT Creator
- Version added :: 0.1.0
The /creator/ /declaration/ of a /manifest/ is expected to a string of one or more
names, of the people and organizations who made the /asset/. It might
be used in a sentence like, "This asset was made by /creator/." Here's
some examples of a /creator/ declaration
*** DRAFT Descrption
- Version added :: 0.1.0
*** DRAFT License
- Version added :: 0.1.0
*** DRAFT Name
- Version added :: 0.1.0
*** DRAFT Versions
- Version added :: 0.1.0
**** DRAFT Source
- Version added :: 0.1.0
***** DRAFT Formats
- Version added :: 0.1.0
***** DRAFT Location
- Version added :: 0.1.0
** DRAFT Data Asset Manifest Channel Structure
A /data asset manifest channel/ is a list of /data asset manifests/.
In the future it may include information abotu the channel, such as
contact information for its maintainer.
** DRAFT Example Data Asset Manifest Channel
   :PROPERTIES:
   :CUSTOM_ID: example-data-asset-manifest-channel
   :END:
- Version added :: 0.1.0
This is my actual /manifest channel/, that I'm maintaining as I
develop this specification.
#+name: my-manifest-channel
#+caption: An included version of my personal /data asset manifest channel/.
#+begin_src elisp
  (setq dam-channels
        '(("emsenn"
           ("brutstrap-css"
            ("name" . "Brutstrap CSS")
            ("description" . "a cascading stylesheet for representing HTML content as it is constructed.")
            ("creator" . "emsenn")
            ("license" . "CC0")
            ("versions"
             ("current"
              ("sourcehut"
               ("location" . "https://git.sr.ht/~emsenn/brutstrap-css/blob/master/")
               ("formats" . ("html" "md" "pdf" "tex" "txt")))))))))
#+end_src
** Functions
*** Overview
The following sections contains functions for working with a /data
asset manifest/ and /data asset manifest channel/. These functions are
implemented in /Emacs Lisp/.

*** Channel Functions
**** DRAFT Get Channels
#+begin_src elisp
  (defun dam-get-channels
      ()
      (loop for channel
            in dam-channels
            collect (car channel)))
#+end_src
**** DRAFT Get Channel
#+begin_src elisp
  (defun dam-get-channel
      (channel)
    (cdr (assoc channel dam-channels)))
#+end_src
**** DRAFT Get Manifests
- Version added :: 0.1.0
This function builds a list of all the /identifiers/ in the given
/channel/.
#+name: define-get-manifests
#+begin_src elisp
  (defun dam-get-manifests
      (channel)
    "Return a list of the manifests recorded in CHANNEL."
    (loop for manifest
          in (dam-get-channel channel)
          collect (car manifest)))
#+end_src
**** DRAFT Get Manifest
- Version added :: 0.1.0
This function returns the /manifest/ of the given /identifier/ on the
given /channel/.
#+name: define-get-manifest
#+begin_src elisp
  (defun dam-get-manifest
      (channel id)
    "Return manifest ID from CHANNEL."
    (assoc id (dam-get-channel channel)))
#+end_src
*** Manifest Functions
**** DRAFT Get Manifest Versions
- Version added :: 0.1.0
#+begin_src elisp
  (defun dam-get-versions
      (channel id)
    "Get the declared versions of ID from CHANNEL."
    (loop for versions
          in (cdr
              (assoc "versions"
                     (dam-get-manifest channel id)))
          collect (car versions)))
#+end_src
**** DRAFT Get Version
- Version added :: 0.1.0
#+begin_src elisp
  (defun dam-get-version
      (channel id version)
    "Return VERSION of ID from CHANNEL."
    (cdr (assoc version (cdr (assoc "versions" (dam-get-manifest channel id))))))
#+end_src
**** DRAFT Get Version Sources
- Version added :: 0.1.0
#+begin_src elisp
(defun dam-get-sources
    (channel id version)
  "Return a list of sources for VERSION of ID."
  (loop for source
        in (dam-get-version channel id version)
        collect (car source)))
#+end_src
**** DRAFT Get Source
- Version added :: 0.1.0
#+begin_src elisp
  (defun dam-get-source
      (channel id version source)
    "Return SOURCE for VERSION of ID."
    (cdr (assoc source (dam-get-version channel id version))))
#+end_src
**** DRAFT Get Source Location
- Version added :: 0.1.0
#+begin_src elisp
  (defun dam-get-location
      (channel id version source)
    "Return the location for VERSION of ID at SOURCE."
    (cdr (assoc "location" (dam-get-source channel id version source)))
    )
#+end_src
**** DRAFT Get Source Formats
#+begin_src elisp
  (defun dam-get-formats
      (channel id version source)
    "Return the available formats for VERSION of ID at SOURCE from
    CHANNEL."
    (cdr (assoc "formats" (dam-get-source channel id version source))))
#+end_src
**** DRAFT Get Format Path
#+begin_src elisp
  (defun dam-get-path
      (channel id version source format)
    "Return a url for the VERSION of ID at SOURCE from CHANNEL in FORMAT."
    (concat
     (dam-get-location channel id version source)
     id
     "."
     format))
#+end_src
** Operations
*** Open Asset in Buffer
- Version added :: 0.1.0
This function is /interactive/ - it can be run as a command. Right now
it assumes you know the exact name of the /channel/, /id/, /version/,
/source/, and /format/ that you want.
#+begin_src elisp
  (defun dam-open-asset
      (channel id version source format)
    "Open VERSION of ID from SOURCE from CHANNEL in FORMAT."
    (interactive "schannel: \nsid: \nsversion: \nssource: \nsformat :")
    (browse-url
     (dam-get-path
      channel id
      version source format)))
#+end_src
* Suppplements
  :PROPERTIES:
  :CUSTOM_ID: supplements
  :END:
** Index
   :PROPERTIES:
   :CUSTOM_ID: index
   :END:
- data asset manifest channel ::
- data asset manifest ::
- data asset ::
- data asset manifest version ::
- data asset manifest source ::
- data asset manifest title ::
- data asset manifest creator ::
- data asset manifest license ::
- data asset manifest identifier ::
- Emacs Lisp function, interactive ::
- Emacs Lisp ::
** README
   :PROPERTIES:
   :EXPORT_FILE_NAME: ./README
   :END:
*** {{{title}}}
#+include: "./source.org::#introduction" :only-contents t
** All Code
   :PROPERTIES:
   :CUSTOM_ID: all-code
   :END:
#+include: "./dam.el" src elisp
** Source
   :PROPERTIES:
   :CUSTOM_ID: source
   :END:
#+include: "./source.org" src elisp

** Footnotes

[fn:1] More precisely, it points to the data representation of such a
work. Rather than "an essay," which is the abstract concept of the
contents of a piece of writing, it points to an /HTML/ file located on
a computer, which is a rendering of the essay. As most folk say "that
article," when referring to "the /HTML/ document hosted on this
specific webserver at this specific address," unless there is a need
to be more precise, I'll refer to the data representation of a thing
(html file containing an essay) as the thing (an essay).