[py-svn] r6980 - py/dist/doc

[hpk at codespeak.net]

Author: hpk
Date: Sun Oct 17 17:12:44 2004
New Revision: 6980

Modified:
   py/dist/doc/future.txt
Log:
more fixes and cleanups 



Modified: py/dist/doc/future.txt
==============================================================================
--- py/dist/doc/future.txt	(original)
+++ py/dist/doc/future.txt	Sun Oct 17 17:12:44 2004
@@ -44,15 +44,14 @@
             if opt.check(): # does the option exist here? 
                 print section.basename, "found:", opt.read() 
 
-Obviously, this would print all string values.   Now the 
-point is that ``find_option()`` would obviously work when 
-``startpath`` is a filesystem-like path like a
-local filesystem path or a subversion URL path. It would
-then see directories as sections and files as option-names 
-and the content of the file as values. 
+Now the point is that ``find_option()`` would obviously work
+when ``startpath`` is a filesystem-like path like a local
+filesystem path or a subversion URL path. It would then see
+directories as sections and files as option-names and the
+content of the file as values. 
 
-But it also works for ``fspy`` paths if you put the following
-python code in a file::
+But it also works (today!) for ``fspy`` paths if you put the following
+python code in the file, referenced as ``startpath`` above::
 
     class Section1:
         someoption = "i am an option value" 
@@ -60,7 +59,7 @@
     class Section2:
         someoption = "i am another option value" 
 
-An ``fspy()`` paths maps classes and modules to directories and 
+An ``fspy()`` path maps classes and modules to directories and 
 name-value bindings to file/read() operations. 
 
 And it could also work for 'xml' paths if you put
@@ -95,7 +94,8 @@
 
 Of course, the somewhat open question is how to make the
 transition from a filesystem path to structured content
-useful and unified (as much as possible without overdoing it). 
+useful and unified, as much as possible without overdoing it, 
+of course. 
 
 Again, there are tasks that will need fully domain specific
 solutions (DOM/XSLT/...) but i think the above view warrants
@@ -126,15 +126,16 @@
   
     assert p.check(func=1, basename='getmsg') 
     getmsg = p.resolve() 
-    # we now a living getmsg() function compiled from the above xml 
+    # we now have a *live* getmsg() function taken and compiled from 
+    # the above xml fragment
 
 Of course, there could be generic converters which convert between 
 different content formats ... allowing configuration files to e.g. 
 be in XML/Ini/python or filesystem-format with some common way 
 to check/iterate for values. 
 
-After all the unix filesystem and the python namespaces are 
-two great honking ideas, why not do more of them? 
+*After all the unix filesystem and the python namespaces are 
+two honking great ideas, why not do more of them?*
 
 
 Revising and improving the import/export system 
@@ -153,16 +154,12 @@
 control can be used by other python packages as well. 
 
 However, all is not fine as the import/export has a 
-few major deficiencies and shortcomings::
+few major deficiencies and shortcomings:
 
 - it doesn't allow to specify doc-strings 
-
 - it is a bit hackish (see py/initpkg.py)
-
 - it doesn't present a complete and consistent view of the API. 
-
 - ``help(constructed_namespace)`` doesn't fully work
-
 - when the py lib implementation accesses parts of itself 
   it uses the native python import mechanism which is 
   limiting in some respects.  Especially for distributed
@@ -237,8 +234,8 @@
 For example, the above approach has some implications, the
 main one being that implementation classes like
 ``py/path/local.LocalPath`` are visible to the caller side but
-present an inconsistency because the user started out with
-``py.path.local`` and expects that the two are really much
+this presents an inconsistency because the user started out with
+``py.path.local`` and expects that the two classes are really much
 the same.  We have the same problem today, of course. 
 
 The naive solution strategy of wrapping the "implementation
@@ -257,11 +254,8 @@
 But this indirection would have interesting advantages: 
 
 - we could easily present a consistent view of the library 
-
 - it could take care of exceptions as well 
-
 - it provides natural interception points for logging 
-
 - it enables remote lazy loading of implementations 
   or certain versions of interfaces 
 
@@ -298,14 +292,11 @@
 shortcomings of the current approach
 ------------------------------------
 
-However, the ``cmdexec`` approach has a few shortcomings:: 
+However, the ``cmdexec`` approach has a few shortcomings: 
 
 - it relies on the underlying system shell
-
 - it neccessitates shell-escaping for expressing arguments
-
 - it does not easily allow to "fix" the binary you want to run.  
-
 - it only allows to execute executables from the local 
   filesystem