[VPM] short question on naming / documenting
darren at DarrenDuncan.net
Thu Jan 22 16:35:44 CST 2004
P.S. Second try: I made the multiple (3) recipients explicit, as the lists don't like bcc. But that also means that you should be careful to only send replies to lists you are a member of, or straight to me only.
I'm looking for a bit of help regarding my SQL::SyntaxModel module/library (currently on CPAN / http://search.cpan.org at version 0.09). Specifically, I am wondering what is the best descriptive name to give a documentation file for it. (Note that this question isn't ultimately Perl-specific, as I will later make a C version of this.)
This module contains SQL schemas and queries, represented as a tree of atomic tokens; it is structurally like an abstract syntax tree or an XML DOM.
The module's API and code make it look like a generic tree, composed of related Nodes; the restrictions for which attributes each Node can have, and its relationship to others, is defined by data (though for efficiency, that data is also contained in the same module and can't be changed at runtime).
As an analogy, the module has an API like a generic XML DOM, but it can enforce a specific XML Schema (the data). The context in which it is used is like a generic database interface. The API basically has an "execute" function, to which a SQL string is given, within that, there is a huge amount of flexability of what the SQL string can say, but it must conform to a specific grammar.
The functional API of SQL::SyntaxModel is basically frozen now (resembling xml dom), and it is fully documented with POD that is in the same file as the code (like most Perl modules).
What I want to do now is create a separate POD-only file which says what all the 'types' of Nodes are, and what attributes and relationships are allowed for each. This file is meant to replace (part or all of) the current DataDictionary.pod and XMLSchema.pod files already in the distribution, and at the same time, make large updates to the design specs already there. Some design specs will be altered, others added, others consolidated, and some removed. (Correspondingly, I would update the 'data' portions of the module.) I was going to make these design fixes at the same time as improving the organization of the documentation itself.
My question for you is what I should name this new document and/or which few terms I should use that give the most accurate message about what it is for, in few words.
I thought of these few, but I'm not sure whether any of them are simply incorrect or not, and/or which are the best (and I'm probably missing something):
(Note: I don't want to use the words 'Syntax' or 'Model' as they are redundant.)
The type of information this file would provide is functionally similar to the SQL design documents, or vendor-specific ones, such as:
Thank you in advance for any suggestions or guidance you can provide. (But I'm not looking for more than a few minutes' effort.)
Have a good day. -- Darren Duncan
More information about the Victoria-pm