RE: [Webware-discuss] RFC: documentation for settings

[Terrel S. <tsh...@uc...>]

On Thu, 2002-04-25 at 07:47, Geoffrey Talvola wrote:
> Terrel Shumway wrote:
> > Yes, this setting is self-explanatory (if you have followed the
> > discussion that spawned it), but (I assume) there are only 
> > two ways you
                                     ^--------^

> I added the setting to the release note file for 0.8 and to the WebKit
> user's guide.  What more could you possibly want?
 
See what happens when you assume 8-)

> I count 54 settings in WebKit.
How did you count? My line noise script missed one.

> Here are the only ones I could find that are
> undocumented:
...
> 	Debug (used for debugging WebKit itself -- does this really need to
> be documented?)
Yes, it *particularly* needs to be documented, because it is not a
simple flag. It seems to be a dictionary with at least a "Sessions" key.
The code that uses it will die if that key is not present. e.g. in
HTTPRequest.py:

   if self._transaction.application().setting('Debug')['Sessions']:

Maybe this could be ...setting('Debug').get('Sessions')


> There are probably more undocumented settings in other parts of Webware
> besides WebKit.

Based on a fresh CVS checkout:
 
[tshumway@localhost Webware]$ for x in $(find -maxdepth 1 -type d); do echo -n $x; find $x -name \*.py |xargs perl -ne 'if (/setting\((.*?)\)/) {print "$1\n";}' |sort -u|grep ^\'|wc -l; done
.     80
./CVS      0
./CGIWrapper     16
./COMKit      1
./Distributions      0
./DocSupport      0
./Docs      0
./Documentation      0
./MiddleKit     13
./MiscUtils      1
./PSP      1
./TaskKit      0
./UserKit      0
./WebKit     53
./WebUtils      0
./bin      3

 
> Already partially done.  Look at WebKit/Docs/Application.configlist and
> WebKit/Docs/AppServer.configlist.  These files are used to auto-generate the
> documentation sections of the user's guide using
> WebKit/DocSupport/config.py.  

Excellent! That is just what I was looking for. (Except that it is
separated from the code, and thus prone to get out of date.)


hmmmm ... (let me ramble a minute to look for patterns)...

The existence of two .configlist files suggests that possibly there
should be one for each .config, but it is not that simple.  .configlist
is actually something like a schema for .config, so each Configurable
should have a .configlist. 

The naming of the .config file is determined at run time by
Configurable.configFilename(). In MiddleKit, each model has a
Settings.config in the model directory. In SitePage and SecurePage, the
.config is in the document tree rather than in the global Configs
directory. This makes it slightly more difficult for MakeAppWorkDir to
create an appropriate setup.


> It's not fully automated though -- you have to
> run config.py and then cut and paste from the resulting file into the user's
> guide.  Still, it only takes a minute or so.

So, you have to manually run config.py from the shell?