Dataface File Structures

[Aoirthoir]

Before I left work yesterday I started to check out the dataface file structures. And what I thought was really complicated seems pretty easy now. Ive also found a lot of files that have informed me about some abilities of dataface I didnt know about previously (example in the path/to/dataface/tables folder, the fields.ini and relationships.ini files).

So I know that you are working on the docs for all of this Mr. Steve, and I am wondering if there is anyway we can help. I am willing to set up domain space and some tables for Dataface so that we can all start adding docs by using dataface itself. Thus we would have a dataface app to start first documenting dataface, and then eventually who knows.

One of the things I think would be helpful is a list of every file. We could add each file to a table specifically for it, specifying what the file does. Maybe even having a code tab from there. We could also have a features table documenting this. So if I want to find out how to do an HTML edit, there would be a record, for that. Basically everything Dataface (and SQL) do can be placed into those tables, of one topic each. Less like a discussion as in your forums here and more a straight single explanation. Like your howtos. I've noticed that a couple of the folks here have begun to use features that they found by looking through the php code. So we could start to help document this which would hopefully ease the burden from you.

Also I saw the SQL for table creates in path/to/dataface/install/dbconfig.sql. I don't know if this is the start of placing the configs for dataface within SQL or not..but even if it isnt, the basics of those tables could start to be used for us to document these things. And perhaps could grow into the dataface configurator thing.

But first and most important is knowing what the capabilites are while at the same time not overloading you. So I imagine we could just create these tables and all of us start adding to it. I still have to create the history thing Ive talked about...Ive been kind of overloaded myself so learning stored procedures has been a bit of a bear. But once that is done this would be very easy to allow any of us, or anyone for that matter, to enter what records we find and then merge them into the regular specs..kind of like a wiki but with less of a free form and more field oriented.

So really from here I don't know where to go or who would be interested. And further what kind of information exactly we need to store and thus the formats of the tables...In the dbconfig.sql mentioned above it has a __fields__ table with some columns like widget:type, widget:label and so on. Some of those (widget:type) I see as being a drop down to a list which could either be an enum or set column or could be a vocabulary link to another table, so as field types are updated we can just add another record...And of course that other table would have more columns, including one for comments or explanations of what the field type does, its advantages and so on...


So if anyone has any ideas or if you would like our help in anything like this Mr. Steve let us know. Really for us to do it we kinda (I think) at this point need your coordination.

Thank you kindly for your consideration.

[shannah]

Thanks for bringing this issue to the forefront. There is *lots* to document, and some of the necessary things are already in place.

I see 2 categories of documentation:
1. Tutorial based
2. Reference docs

Plone provides this nice documentation section for creating the tutorials so time is the only limiter here.

As far as reference docs go, there are 3 sub-categories:
1. Concepts (e.g. relationships, valuelists, etc..)
2. API Docs (available at http://dataface.weblite.ca)
3. Misc reference docs (including reference about fields.ini/valuelists.ini/relationships.ini/actions.ini/permissions.ini options).

I believe that Plone offers reasonably good facilities for creating #1 and #3, while I have developed a searchable documentation generator to take care of #1. I believe that anything that can be generated from the source code, should be done that way, and only to do custom documentation in areas where source code docs won't suffice.

AFAIK you should be able to add your own documents to the documentation section of the dataface website. If we want to reposition things later, Plone makes it easy to cut and paste into different sections of the site.


---- On other topics -----
The dbconfig.sql file is a remnant of an experiment a few months back trying to store the config in the database instead of in INI files. At the time I didn't have the time to iron out all the kinks in this so I just left it. That database schema is partial and would have to be modified to accommodate many of the new options in dataface 0.6. Personally I don't need database storage for the schemas at this time so I probably won't be getting back to this for a while.

Thanks for the offer of help with the documentation. I appreciate it and certainly could use the help. Certainly when the forum is upgraded to be searchable, that will help, and if people start leaving comments on the appropriate pages of the API docs with their own snippets and tips the documentation pool can begin to grow... Little by little we will get everything documented.

Best regards

Steve

[Aoirthoir]

Ok cool.

Regarding dbconfig.sql that is cool. I can use it as the start of Ive been thinking. Once I know more about what can be done, I can start to add my own fields to it to cover the widgets available. Unless we can come up with a more dynamic way to do so (A record/row widget thing perhaps..), this will work for now. Even if we change it later SQL makes this easy.

As to helping you with the docs, I know I and I imagine others are ready whenever. I will have to start learning the code. And go from there. Though if you have any suggestions, or want to give assignments (so to speak) I'd be willing to start wherever you suggest.

[shannah]

A good start for suggestions on the documentation would be to go to the api docs and search for the docs you are looking for. Keep track of the search words that you use, and let me know what you searched for, and what you would have liked to have come up. I can work on customizing the API docs and its search functionality to give better results.

Best regards

Steve

[Aoirthoir]

ok I will start on that this week. Thanks for the help.

One thing I know I am definitely interested in is knowing all of the widgets. Basically anything that can go into the Fields.ini, valuelists.ini or relationships.ini. Or even any of the INI files that dataface uses. (SHort of SQL...because that is our responsibility to learn).