/Docs/S/About/Tech/Spec/0.md
Document views: Document Xray Visual Cicero Print   Source views: Source JSON(ish)   On GitHub: File ~PageRank   (rare: 'ShowMe' 1)
Tech:
  1. Packages ("Cmacclets")
    A set of files organized as Doc/; File/; query/; and vendor/.
    1. Doc/ has Cmacc text. (Should the folder be called "Record/" or "Cmacc/" ?)
    2. File/ can have "data" of any nature. The goal is to be able to communicate a data package - for instance an a/v work or a medical scan - with accompanying text and functions.
    3. query/ and vendor/ are technical (suggested by lower-case). ("query/" is a better label for what is currently called "view" in the existing implementations. "vendor/" is used for code - and some hosting systems currently require that name.
  2. Records
    1. Implemented Features of Records
      1. A "Record" is an ordered list of key/values.
      2. The "Values" are strings. They can be understood as:
        1. html;
        2. the name of another Record;
        3. something else, for instance some computer code or a comment.
    2. "Punctuation"
      The rendering engine should work with a variety of formats:
      1. The current flat file, source-code resembling. This enables use with tools of software collaboration. (Legal source prose is like software source code.)
      2. JSON, for instance in blockchains, IPFS, etc.
      3. XML
      4. Databases - SQL and graph - for enterprise management.
      5. Google Docs - and why not have a mode that disrenders the text (makes into key=values) and then rerenders it with possible overrides.
  3. Cmacc-compliant rendering for blockchain and other databases:
    1. Example of a JSON-formatted query
      Example of a query done as a JSON snippet.
    2. Queries
      1. A CommonAccord "document" is a report from a database (conventional, blockchain, file system, graph), where the "query" is special. The query asks for a rendering engine to be applied. The rendering engine is parameterized with a number of different possibilities. These are some useful parameterizations of the rendering engine:
        1. "xray" view with each value wrapped with metadata relating to its source file and key name. Enough info to permit interface to allow pop-up editing.
        2. "doc" view with each Value wrapped in its key, but not the file name. Like the current Doc view. Does not reveal the file structure of the generating party.
        3. "print" view without wrapping.
        4. "used" list of key/values actually used in rendering the document, so can provide to another party in "source" form without disclosing the internal organization.
        5. "missing" list of keys not found.
      2. All the other "views" currently in the CommonAccord app are common database queries, where an interface has been applied to the return. For example:
        1. "edit" view of the raw text in editable mode
        2. "raw" mode the text, no editing
        3. "map"(?) (currently called Source) view of the text of the Record with nice presentation, and file names linked for navigation.
        4. "find" a (partial) listing of keys and values available. Could be part of graph navigation via "map."
    3. Render (parameter)
      1. Rendering is Expansion of a Value
        1. A "Document" is the result of rendering a "Record".
        2. Rendering is done by expanding the Value of a specified Key - by default it is currently "Model.Root" - with recursive expansion of {plugs} in the Value.
        3. Plugs are expanded by literal matching with the Plug name with the first matching Key name in the namespace of the Record.
      2. The Key namespace of a Record
        The Key namespace of a Record1 is:
        1. the Keys in Record1,
        2. for each RecordN referenced as a Value in Record1 - the Keys in RecordN:
          1. If a RecordN is referenced by an empty Key, the Keys and Values are included as is.
          2. If a RecordN is referenced by a Key which has a name, that name is "prefixed" to each of the Keys and the Plugs in RecordN.
            1. E.g., a reference Foo.=[Record2] means that a Key/Value in Record2 of "sec=My {Name}." would be evaluated as Foo.sec=My {Foo.Name}.
            2. If a Key called "Foo.Name" is not found, the prefix is removed and "Name" is tried. This deprefixing is both (i) essential in many uses, and (ii) a consequence of the object model.
        3. recursively, depth-first.
      3. Ordered versus Unordered List
        Currently, the order of Keys in a Record is significant.
        1. A Record may contain more than one Key with the same name - the top one has priority.
        2. It is common to reference a number of RecordNs via the same Key, notably with an empty Key.
        3. Multiple Key/Values is otherwise of minor use.
        It would be possible to develop a naming convention for Keys that indicated order. For instance (1)=[High_Priority.md], (2)=[Next_Priority.md]
  4. Future Possible Extensions
    1. Smart Folders
      A very useful extension would be "smart" Folders.
      1. For example, to replace the mass of Records currently at Z/ol/*, a smart folder could intercept the request for a file and return a (calculated) Record.
      2. Of course, smart Folders would respect the object model. An actual Record would have precedence over a calculated one.
    2. Rendering
      The following seem necessary extensions to rendering:
      1. There needs to be a naming convention for the _second, and _third_, etc. highest priority Key in the Record's namespace. Foo=This value used to say: {Foo//-1}.
      2. The namespace (path) of Records can be augmented by specifying another, additional path. This additional Path2 adds to the namespace of the Path in the same way that referencing a Record2 adds to the namespace of a Record. The Path2 is treated as having higher priority than the basic Path.
      3. It is desired to keep the functions and syntax very simple. The functions that remain somewhat cumbersome include:
        1. Automatic numbering of cross-references. These can be parameterized, but there is still a bit of work. (Can be handled via interface.)
        2. Calculation of values such as sums of a column of numbers. Can be handled by interface, or by smart contract.
        In each case, persisting the value as a standard Key/Value in a Record may increase certainty by keeping the data simple.