Author: chrisz
Date: Sun Sep 17 12:18:24 2006
New Revision: 5709
Added:
Webware/trunk/WebKit/Docs/Future.html (contents, props changed)
Modified:
Webware/trunk/WebKit/Docs/InstallGuide.html
Webware/trunk/WebKit/Docs/UsersGuide.html
Log:
Recreated HTML pages from ReST files.
Added: Webware/trunk/WebKit/Docs/Future.html
==============================================================================
--- (empty file)
+++ Webware/trunk/WebKit/Docs/Future.html Sun Sep 17 12:18:24 2006
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<title>Future Work</title>
+<link rel="stylesheet" href="../../Docs/Doc.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="future-work">
+<h1 class="title">Future Work</h1>
+<p>Webware for Python</p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Version:</th><td class="field-body">X.Y</td>
+</tr>
+<tr class="field"><th class="field-name">Released:</th><td class="field-body">@@/@@/@@</td>
+</tr>
+</tbody>
+</table>
+<div class="section">
+<h1><a id="warning" name="warning">Warning</a></h1>
+<p>This document is mostly outdated and out of touch with development.
+You can find better information about known bugs and future work
+in the <a class="reference" href="http://wiki.w4py.org">Wiki</a> and in the <a class="reference" href="http://sourceforge.net/tracker/?group_id=4866">SourceForge tracker systems</a>,
+both accessible from the <a class="reference" href="http://www.webwareforpython.org">Webware Home Page</a>.
+The SourceForge task manager is currently not used since these systems should
+be sufficient and we do not want to scatter issues in too many systems.</p>
+</div>
+<div class="section">
+<h1><a id="future-work-limitations" name="future-work-limitations">Future Work/Limitations</a></h1>
+<p>Sprinkled throughout the code are comments tagged with <tt class="docutils literal"><span class="pre">@@</span></tt> which are
+hopefully accompanied by a date and someone's initials. These comments
+represent things to be done. The double at-sign (<tt class="docutils literal"><span class="pre">@@</span></tt>) convention was
+chosen because it doesn't appear to be used for anything else.</p>
+<p>In addition to the inline comments, some significant items have been
+recorded below. These are future ideas, with no commitments or timelines
+as to when/if they'll be realized. The Python WebKit is open source,
+so feel free to jump in!</p>
+<div class="section">
+<h2><a id="known-bugs" name="known-bugs">Known Bugs</a></h2>
+<p>All major known bugs that existed previously have been fixed.</p>
+</div>
+<div class="section">
+<h2><a id="to-do" name="to-do">To Do</a></h2>
+<div class="section">
+<h3><a id="major-items" name="major-items">Major Items</a></h3>
+<ul class="simple">
+<li>CheckSource.py: A program to check the source code conventions.</li>
+<li>Role-based security and user-authentication. Goal is to eliminate,
+as much as possible, developer-written security logic.
+This should be provided by the WebKit and be configurable.</li>
+<li>Write a custom adaptor for Apache, Netscape, MS, etc.</li>
+<li>Distribution and load balancing.</li>
+<li>Fault tolerance.</li>
+<li>More sophisticated admin tools including password protection,
+clearing logs, displaying a maximum of information at a time, etc.
+Consider using module 'resource'.</li>
+<li>Investigate case insensitive URLs, especially for the Windows platform.</li>
+<li>Plug-ins:
+* In ExamplePage, automatically support examples of any plug-in
+* Better docs
+* Properties.config. 'Load', 0, 1 or the name of the required op sys</li>
+</ul>
+</div>
+<div class="section">
+<h3><a id="general" name="general">General</a></h3>
+<ul class="simple">
+<li>Hunt down: <tt class="docutils literal"><span class="pre">@@</span></tt> tags (which signify "To Be Done"s), <tt class="docutils literal"><span class="pre">FUTURE</span></tt> items
+in class doc strings, <tt class="docutils literal"><span class="pre">NotImplementedErrors</span></tt>, <tt class="docutils literal"><span class="pre">--</span></tt> tags</li>
+<li>Code clean up.</li>
+<li>Right now, if the Application itself (as opposed to Servlets) throws
+an exception, it doesn't get captured nicely. However, it is displayed
+in the app server's console.</li>
+<li>The exception handler is pretty nice and has features like logging,
+e-mail, gathering debugging info, etc.
+However, on occasions it can throw exceptions too.
+There should be a simpler, secondary exception handler for when this happens.</li>
+<li>Review the timestamp caching logic and its relation to .pyc files if any.</li>
+<li>Add "Last-modified:" to generic files that are served via WebKit.</li>
+<li>If a Python file has only one class that inherits from Servlet,
+then use that as the Servlet class
+(rather than requiring the name be the same as the file).</li>
+</ul>
+</div>
+<div class="section">
+<h3><a id="testing" name="testing">Testing</a></h3>
+<ul class="simple">
+<li>Provide testing web page where people can report their testing results
+including version numbers, etc.</li>
+<li>Provide higher level automation of testing. For example, a testing script
+should be able to launch various app servers multiple times.</li>
+<li>Provide highly automated benchmarking so we can track changes in performance.</li>
+<li>Expand the regression test suite.</li>
+</ul>
+</div>
+<div class="section">
+<h3><a id="docs" name="docs">Docs</a></h3>
+<ul class="simple">
+<li>Add a Getting Started Guide and a Screencast.</li>
+<li>Beef up the User's Guide and Tutorial.</li>
+<li>User's Guide: Create a caching section to discuss the virtues of doing so
+(the Color example became 12 X faster on the server side).</li>
+</ul>
+</div>
+<div class="section">
+<h3><a id="food-for-thought-considerations-reviews" name="food-for-thought-considerations-reviews">Food for thought, considerations, reviews</a></h3>
+<ul class="simple">
+<li>Consider including FormKit, FunFormKit or FormEncode:
+A plug-in to aid the construction and validation of forms.</li>
+<li>Consider adding a simple helper lib for generating HTML
+(such as SimpleHTMLGen) to the WebUtils package.</li>
+<li>Support <a class="reference" href="http://www.python.org/dev/peps/pep-0333/">WSGI</a>.</li>
+<li>Consider this statement from the FastCGI docs:
+"Redirects are handled similar to CGI. Location headers with values
+that begin with "/" are treated as internal-redirects; otherwise,
+they are treated as external redirects (302)."</li>
+<li>FastCGI app server:
+The idea is that if the app server itself supports FastCGI,
+then it can be used directly with FastCGI enabled web servers
+sans the infamous "adapter".
+Dan Green has brought this up in Webware-discuss.</li>
+<li>Consider if we need to support <tt class="docutils literal"><span class="pre"><form</span> <span class="pre">action="x.py?a=1"</span> <span class="pre">method="post"></span></tt>
+where you will have both a query string and posted data.</li>
+<li>Application modifies sys.path so that servlets can say
+<tt class="docutils literal"><span class="pre">from</span> <span class="pre">SuperServlet</span> <span class="pre">import</span> <span class="pre">SuperServlet</span></tt> where SuperServlet is located in
+the same directory as the Servlet. We'd prefer a more sophisticated technique
+which does not modify sys.path and does not affect other servlets. (Or maybe
+this would go away with a new one-process-per-application architecture.)</li>
+</ul>
+</div>
+<div class="section">
+<h3><a id="check-out" name="check-out">Check out</a></h3>
+<ul class="simple">
+<li><a class="reference" href="http://pythonpaste.org">Python Paste</a></li>
+<li><a class="reference" href="http://www.djangoproject.com">Django</a></li>
+<li><a class="reference" href="http://www.turbogears.org">TurboGears</a></li>
+<li><a class="reference" href="http://pylonshq.com">Pylons</a></li>
+<li><a class="reference" href="http://webpy.org">web.py</a></li>
+<li><a class="reference" href="http://aquarium.sourceforge.net">Aquarium</a></li>
+<li><a class="reference" href="http://www.zope.org/Members/Amos/WhatIsAcquisition">http://www.zope.org/Members/Amos/WhatIsAcquisition</a></li>
+<li><a class="reference" href="http://www.zope.org/Members/jim/Info/IPC8/AcquisitionAlgebra/index.html">http://www.zope.org/Members/jim/Info/IPC8/AcquisitionAlgebra/index.html</a></li>
+<li>FastCGI related: <a class="reference" href="http://www.tfarmbruster.com/fcgi_sa.htm">http://www.tfarmbruster.com/fcgi_sa.htm</a></li>
+</ul>
+</div>
+<div class="section">
+<h3><a id="down-the-road" name="down-the-road">Down the road</a></h3>
+<ul class="simple">
+<li>Multi-language support/localization (e.g., vend data to clients
+in their preferred written language)</li>
+<li>Consider CORBA standard RMI-IIOP and it's potential interaction with WebKit.
+This technology has been marked for inclusion in J2EE. I imagine the idea
+might be that an app server could be used by more than just web browsers.
+e.g., it could be used programmatically
+(in a more natural way than simulating a web client).</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+</body>
+</html>
Modified: Webware/trunk/WebKit/Docs/InstallGuide.html
==============================================================================
--- Webware/trunk/WebKit/Docs/InstallGuide.html (original)
+++ Webware/trunk/WebKit/Docs/InstallGuide.html Sun Sep 17 12:18:24 2006
@@ -302,9 +302,9 @@
</div>
<div class="section">
<h1><a class="toc-backref" href="#id28" id="updating-webware" name="updating-webware">Updating Webware</a></h1>
-<p>When updating to a new version of Webware, you should look into the
-WebKit release notes whether it will be required to recreate the
-working directories of your Webware applications.</p>
+<p>When updating to a new major or minor version of Webware, check whether
+the Webware release notes recommend updating or recreating the working
+directories of your Webware applications.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id29" id="architecture" name="architecture">Architecture</a></h1>
Modified: Webware/trunk/WebKit/Docs/UsersGuide.html
==============================================================================
--- Webware/trunk/WebKit/Docs/UsersGuide.html (original)
+++ Webware/trunk/WebKit/Docs/UsersGuide.html Sun Sep 17 12:18:24 2006
@@ -41,14 +41,15 @@
<li><a class="reference" href="#dumping-thread-stack-frames" id="id33" name="id33">Dumping Thread Stack Frames</a></li>
<li><a class="reference" href="#restarting-the-server" id="id34" name="id34">Restarting the Server</a></li>
<li><a class="reference" href="#assertions" id="id35" name="id35">Assertions</a></li>
-<li><a class="reference" href="#html-validation" id="id36" name="id36">HTML Validation</a></li>
+<li><a class="reference" href="#using-wingide" id="id36" name="id36">Using WingIDE</a></li>
+<li><a class="reference" href="#html-validation" id="id37" name="id37">HTML Validation</a></li>
</ul>
</li>
-<li><a class="reference" href="#naming-conventions" id="id37" name="id37">Naming Conventions</a></li>
-<li><a class="reference" href="#actions" id="id38" name="id38">Actions</a></li>
-<li><a class="reference" href="#plug-ins" id="id39" name="id39">Plug-ins</a></li>
-<li><a class="reference" href="#how-do-i-develop-an-app" id="id40" name="id40">How do I develop an app?</a></li>
-<li><a class="reference" href="#known-bugs" id="id41" name="id41">Known Bugs</a></li>
+<li><a class="reference" href="#naming-conventions" id="id38" name="id38">Naming Conventions</a></li>
+<li><a class="reference" href="#actions" id="id39" name="id39">Actions</a></li>
+<li><a class="reference" href="#plug-ins" id="id40" name="id40">Plug-ins</a></li>
+<li><a class="reference" href="#how-do-i-develop-an-app" id="id41" name="id41">How do I develop an app?</a></li>
+<li><a class="reference" href="#known-bugs" id="id42" name="id42">Known Bugs</a></li>
</ul>
</div>
<div class="section">
@@ -248,7 +249,31 @@
</pre>
</div>
<div class="section">
-<h2><a class="toc-backref" href="#id36" id="html-validation" name="html-validation">HTML Validation</a></h2>
+<h2><a class="toc-backref" href="#id36" id="using-wingide" name="using-wingide">Using WingIDE</a></h2>
+<p>Here is what you need to do in order to debug a Webware web site
+using the <a class="reference" href="http://wingware.com">WingIDE</a> development environment:</p>
+<ul>
+<li><p class="first">Use the <a class="reference" href="InstallGuide.html#makeappworkdir">MakeAppWorkDir</a> script
+to make a local app work dir for your project.</p>
+</li>
+<li><p class="first">Create a run-debug.py script in the work directory with these contents:</p>
+<pre class="literal-block">
+import sys, Launch
+Launch.main([sys.argv[0]] + ['DebugAppServer'] + sys.argv[1:])
+</pre>
+</li>
+<li><p class="first">Add that file to the WingIDE project if you haven't already.</p>
+</li>
+<li><p class="first">Right-click and choose "Set As Main Debug File".</p>
+</li>
+</ul>
+<p>Now you can run from WingIDE, set break points, examine the stack, use
+a Python prompt tied to any stack prompt, etc.</p>
+<p>WingIDE also has a "Debug > Attach to Process..." command which could
+be useful to debug a test or production server.</p>
+</div>
+<div class="section">
+<h2><a class="toc-backref" href="#id37" id="html-validation" name="html-validation">HTML Validation</a></h2>
<p>You can validate the HTML in your pages using the <a class="reference" href="http://www.htmlhelp.com/tools/validator/">Web Designer
Group's HTML Validator</a>. It is available as a <a class="reference" href="http://www.htmlhelp.com/tools/validator/packages/">RPM package</a>, in
Debian as <tt class="docutils literal"><span class="pre">wdg-html-validator</span></tt> and you can also install the <a class="reference" href="http://www.htmlhelp.com/tools/validator/source.html">source</a>.</p>
@@ -264,7 +289,7 @@
</div>
</div>
<div class="section">
-<h1><a class="toc-backref" href="#id37" id="naming-conventions" name="naming-conventions">Naming Conventions</a></h1>
+<h1><a class="toc-backref" href="#id38" id="naming-conventions" name="naming-conventions">Naming Conventions</a></h1>
<p>Cookies and form values that are named with surrounding underscores
(such as <tt class="docutils literal"><span class="pre">_sid_</span></tt> and <tt class="docutils literal"><span class="pre">_action_</span></tt>) are generally reserved by WebKit
and various plugins and extensions for their own internal purposes. If
@@ -274,7 +299,7 @@
they won't break your application.</p>
</div>
<div class="section">
-<h1><a class="toc-backref" href="#id38" id="actions" name="actions">Actions</a></h1>
+<h1><a class="toc-backref" href="#id39" id="actions" name="actions">Actions</a></h1>
<p>Suppose you have a web page with a form and one or more
buttons. Normally, when the form is submitted, a method such as
Servlet's <tt class="docutils literal"><span class="pre">respondToPost()</span></tt> or Page's <tt class="docutils literal"><span class="pre">writeBody()</span></tt>, will be
@@ -321,7 +346,7 @@
procede as in 2. in such cases.</p>
</div>
<div class="section">
-<h1><a class="toc-backref" href="#id39" id="plug-ins" name="plug-ins">Plug-ins</a></h1>
+<h1><a class="toc-backref" href="#id40" id="plug-ins" name="plug-ins">Plug-ins</a></h1>
<p>A plug-in is a software component that is loaded by WebKit in order to
provide additional WebKit functionality without necessarily having to
modify WebKit's source.</p>
@@ -335,7 +360,7 @@
information about writing your own.</p>
</div>
<div class="section">
-<h1><a class="toc-backref" href="#id40" id="how-do-i-develop-an-app" name="how-do-i-develop-an-app">How do I develop an app?</a></h1>
+<h1><a class="toc-backref" href="#id41" id="how-do-i-develop-an-app" name="how-do-i-develop-an-app">How do I develop an app?</a></h1>
<p>The answer to that question might not seem clear after being deluged
with all the details. Here's a summary:</p>
<ul class="simple">
@@ -374,7 +399,7 @@
</ul>
</div>
<div class="section">
-<h1><a class="toc-backref" href="#id41" id="known-bugs" name="known-bugs">Known Bugs</a></h1>
+<h1><a class="toc-backref" href="#id42" id="known-bugs" name="known-bugs">Known Bugs</a></h1>
<p>Known bugs and future work in general are documented in <a class="reference" href="Future.html">Future</a>.</p>
<p>Credit</p>
<p>Authors: Chuck Esterbrook, Jay Love, Geoff Talvola, Ian Bicking
|