What is the naming scheme?! #2
Description
@HazardJ has been fiddling with naming schemes for some years. With this repository, it is proposed that we take advantage of found objects - to wit, the WorldWideWeb and GitHub. So, files can be organized according to the web domain of the proponent, or according to the Github organization and repo name. These can be managed as local files, or the whole of GH/ and W/ (or GitHub/ and WWW/ ?) can be aliases for files at those destinations.
See https://github.com/CommonAccord/Cmacc-Startup2/blob/master/Doc/include.php (@dazzaji, someone else, how do I make a link to a file in the repo?)
This defines, in essence, a proponent's exclusive space.
Within that space it is suggested (by me and my experience) that we suggest a type of organization. This is of course not mandatory, but might be helpful. My experience is that two folders are helpful - one for forms and the other for components. Most components of most forms will be "sections" so, Form/ and Sec/. Note the initial caps. This distinguishes from the web domains, and CamelCase is easier to read (@dazzaji has made this point, too).
From there, we get into mostly details, but one of them stands out. The "extension" of the files (.md, but could have been .cmacc or the like), is important. It tells GitHub how to present the file when you go to the source there. It tells your computer what editor to use when you double-click the file. We have been using .md and had good experience with that. It has been objected that we are overloading the .md extension name. That a Cmacc file is not markdown. It's something else. That seems accurate as a technical matter, but pragmatically, .md works well. So if/until GitHub makes special accommodation for .cmacc or the like, I suggest we stick with .md. (Note that some common files don't have .md, such as the ones that make outlines, in Z/. It seems pedantic to have those rarely edited bits have .md, and adds a bit of cruft when you use them.
The next most systemic issue is probably the names that denote parts of a document. In the Z/ folder, there are lots of little widgets that make it easy to put documents together or cut up an existing document and automate it. These are of course not exclusive, they are just more folders of files, and we can always make more. They assume an organization of sections as "Sec" means a section and its title. "sec" means the content of the section (without its title). "Ti" (chosen because it works in English/French/German and probably a lot of places of romance) means Title/Titre/Titel. Within the content of a section (the "sec" part) there is the possibility of an introductory line or paragraph, then a list, and then an extroductory line or paragraph. There is a naming convention for those, too, built into the stuff at Z/. The intro is 0.sec, the extro is 90.sec (if you have more than 89 paragraphs in a section you either rethink it or make your own). They could be Intro.sec and Extro.sec just as easily (remember that everything is just names, there is no calculation).
Into the weeds:
The name of the actual files (as opposed to the folders that organize them) could be long and expressive. I've played with that a lot. But, that seems cumbersome and a bad tradeoff. More sensible is to make the file names short and merely state their function. So ... Wx/org/nvca/SPA/Sec/cRep_v01.md is the Company representations. This could be made more expressive - /CompanyRepresentations_v01.md, though if you work with these files a bit, cRep is a bit less work to read. But, skipping that weed on a weed, the point is that I didn't name the file NVCA_SPA_cRep_v01.md. Because that info is already in the path. This works fine as long as the file is in the file system. Which is where it should be, so this seems a better than the repetition of Wx/org/nvca/SPA/Sec/NVCA_SPA_cRep_v01.md.
Out onto the fields:
Of course all of these things can be further automated. The Z/ things could be done as some bit of code that provided quicker responses, had more features and didn't take some 800 files to count to 40. The W/ could actually fetch from the web, and GH/ from GitHub.
The form of a variable - {some thing} - allows spaces, so one can put programming expressions into a document and your parser could default (after looking to see if there was a literal keyname match) to a programming environment. This has lots of potential uses, and is totally necessary for even such common tasks as adding price times quantity. Automatic numbering of cross-references is another common example. There is a pretty good way to do it natively, but perhaps people will want this to be fully automated.
Above our heads:
All this CommonAccord text is legal fodder for real deals. It can be used natively (Be-Bound does.) But it is most likely to be a resource for real transaction systems - such as blockchain. So, the fit with identity and place (U/) and with automation (adding price times quantity and applying a discount) will be done in those systems. CommonAccord, and the Cmacc document model, is a place to do text.