/Docs/S/About/Tech/Spec/0.md
Source views: Source JSON(ish) on GitHub (VSCode) Doc views: Document (&k=r00t): Visual Print Technical: OpenParameters Xray
Tech:
>- Packages ("Cmacclets")
A set of files organized as Doc/; File/; query/; and vendor/. - Doc/ has Cmacc text. (Should the folder be called "Record/" or "Cmacc/" ?)
- 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.
- 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.
>Records
>- Implemented Features of Records
>- A "Record" is an ordered list of key/values.
- The "Values" are strings. They can be understood as:
- html;
- the name of another Record;
- something else, for instance some computer code or a comment.
>
>"Punctuation"
The rendering engine should work with a variety of formats:- The current flat file, source-code resembling. This enables use with tools of software collaboration. (Legal source prose is like software source code.)
- JSON, for instance in blockchains, IPFS, etc.
- XML
- Databases - SQL and graph - for enterprise management.
- Google Docs - and why not have a mode that disrenders the text (makes into key=values) and then rerenders it with possible overrides.
>>Cmacc-compliant rendering for blockchain and other databases:
>- Example of a JSON-formatted query
Example of a query done as a JSON snippet. - Queries
>- 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:
- "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.
- "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.
- "print" view without wrapping.
- "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.
- "missing" list of keys not found.
> - All the other "views" currently in the CommonAccord app are common database queries, where an interface has been applied to the return. For example:
- "edit" view of the raw text in editable mode
- "raw" mode the text, no editing
- "map"(?) (currently called Source) view of the text of the Record with nice presentation, and file names linked for navigation.
- "find" a (partial) listing of keys and values available. Could be part of graph navigation via "map."
>>Render (parameter)
>- Rendering is Expansion of a Value
>- A "Document" is the result of rendering a "Record".
- Rendering is done by expanding the Value of a specified Key - by default it is currently "r00t" - with recursive expansion of {plugs} in the Value.
- Plugs are expanded by literal matching with the Plug name with the first matching Key name in the namespace of the Record.
>The Key namespace of a Record
The Key namespace of a Record1 is:- the Keys in Record1,
- for each RecordN referenced as a Value in Record1 - the Keys in RecordN:
- If a RecordN is referenced by an empty Key, the Keys and Values are included as is.
- 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.
- 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}.
- 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.
>
>recursively, depth-first.>Ordered versus Unordered List
Currently, the order of Keys in a Record is significant. - A Record may contain more than one Key with the same name - the top one has priority.
- It is common to reference a number of RecordNs via the same Key, notably with an empty Key.
- 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]>>Future Possible Extensions
>- Smart Folders
A very useful extension would be "smart" Folders.- 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.
- Of course, smart Folders would respect the object model. An actual Record would have precedence over a calculated one.
>Rendering
The following seem necessary extensions to rendering:- 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}.
- 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.
- It is desired to keep the functions and syntax very simple. The functions that remain somewhat cumbersome include:
- Automatic numbering of cross-references. These can be parameterized, but there is still a bit of work. (Can be handled via interface.)
- 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. >>>