source: branches/unified_backend/README_DEVELOPERS.txt @ 72

Last change on this file since 72 was 72, checked in by yermol, 15 years ago

work-in-progress commit to Unified Backend branch.

added devutils directory for server side convenience scripts

svn_commit.pl front-end to svn commit to update about.html on submit.
makedocs.pl to generates JSDoc and PHPDoc documentation.

added Configure.php script to generate cli script paths and to set perms.
added index.html
added README, INSTALL, README_DEVELOPERS
added examples/simple_example.html
added ddt.js debug trace message to text area class.
htmlarea.js reworked

  • reorganized to group related pieces together.
  • JSDoc headers added to all methods
  • debugging trace messages added to entry points of most methods.
File size: 6.9 KB
Line 
12005-04-15
2                   
3              Xinha Unified Backend Branch
4                    Development Info
5
6by: Yermo Lamers
7http://www.formvista.com
8
9----------------------------------------------------------
10             Configure.php
11----------------------------------------------------------
12
13To avoid hard coding paths, I've hacked together a small
14Configure.php system which will generate various scripts
15and set directory permissions based on conf files in ./conf.
16
17Configure.php must be called from the command line using the
18full path to command line PHP. This script must be run first
19before any other development scripts can be run.
20
21----------------------------------------------------------
22             Dev Environment Scripts
23----------------------------------------------------------
24
25These scripts assume the availability command line PHP and Perl.
26
27These script have not been tested under Windows. If there is sufficient
28interest, I can make them portable to Windows.
29
30The devutil scripts are located on ./devutils and they include:
31
32svn_commit.php
33
34  preprocessor to "svn commit" command that updates the
35  popups/about.html file so that it always includes the current
36  revision info.
37
38  Requires command line "svn" command to be in $PATH
39
40buildruntime.php: - not done
41
42  generates a "runtime" version of xinha_ub with all comments
43  and debug trace messages stripped out. It also does
44  in-line text replacement for some specific tags.
45
46ddtpreproc.php - not done
47
48  Javascript does not seem to have a version of PHP's
49  __LINE__ and __FILE__ constants so there is no clean way of
50  including file and line numbers in ddt trace messages; at least
51  none that I've been able to find. This script preprocesses the
52  javascript source files to patch in file and line numbers to
53  every _ddt() call.
54
55makedocs.pl
56
57  Calls JSDoc with some arguments to generate the class documentation
58  from the source javascript files. Requires Perl, JSDoc and PHPDoc
59  to run.
60 
61  NOTE: Under RedHat 9, JSDoc will cause perl to dump core when running
62  on htmlarea.js. Upgrading Perl to 5.8.6(from source) fixed the
63  problem for me).
64
65IMPORTANT:
66
67      DO NOT FIELD THESE SCRIPTS ON A LIVE SITE.
68
69I have added "deny from all" .htaccess files and each scripts
70checks it's environment in an attempt to avoid being run from
71a webserver.
72
73If you are not running Apache or aren't permitted to do overrides
74in .htaccess, you may want to move the ./devutils directory
75somewhere outside of DOCUMENT_ROOT.
76
77----------------------------------------------------------
78             Code Re-Org
79----------------------------------------------------------
80
81In an attempt to make the codebase more manageable I've
82reorganized htmlarea.js to group related items together.
83
84The file is now broken into five sections:
85
861. Initial Setup
872. HTMLArea.Config Class
883. HTMLArea class methods
894. HTMLArea Class
905. Misc Support overrides and functions
91
92----------------------------------------------------------
93               JSDoc and PHPDoc.
94----------------------------------------------------------
95
96I found a perl script that implements a JavaDoc style system
97for JavaScript. See http://jsdoc.sourceforge.net/.
98
99JSDoc is very sensitive to the order of tags in the headers.
100If you try to add doc headers and they are not showing up
101correctly compare with the test.js file distributed with JSDoc.
102
103JSDoc seems to lack the ability to link to the actual source
104code definition of a given class or method.
105
106I've added JSDoc headers to just about everything I've touched.
107
108For the PHP scripts that I touch, I'm adding PHPDoc headers.
109
110There is a ./utils/makedocs.pl shell script.
111
112----------------------------------------------------------
113             Debugging Trace Messages
114----------------------------------------------------------
115
116To further make my life easier and come up to speed, I've added
117trace messages to virtually every method using a contributed version
118of my DDT debug-trace-message-to-textarea class. These messages can
119be turned on and off on a per-class basis using the ddtOn() method.
120
121There is also a global trace message object included in the full_example-body.html
122file to trace out the editor startup. At that point the page is not completely
123constructed so a popup window is used to house these trace messages.
124
125What's nice is you can quickly get a feel for the order in which things happen
126and which methods are invoked for what events.
127
128Unfortunately, the trace message infrastructure adds a tremendous amount of processing
129and size to the distribution. With all debug messages turned on, this branch of
130Xinha is pretty much unuseable as an editor.
131
132The concept is to do development on the trace enabled version of the code and then
133generate a stripped "runtime" version using the provided ./utils/make_runtime.sh
134script. make_runtime strips all debugging code out of the .js files. It also removes
135almost all comments to reduce file size. I am envisioning having two distributions
136of Xinha .. a development version with all debugging intact and a runtime version
137that has been stripped. (this has served me extremely well in formVista development)
138
139Debug trace messages can be enabled in one of two ways:
140
1411. uncommenting the _ddtOn() calls in the example HTML page and in htmlarea.js
1422. clicking the new '<>' icons which turn on trace messages
143
144----------------------------------------------------------
145                      Coding Style
146----------------------------------------------------------
147
148The original coding style guidelines included in the code were:
149
150---------------------------------------------------
151 Developers - Xinha main branch Coding Style by Gogo:
152
153    For the sake of not committing needlessly conflicting changes,
154
155   - New code to be indented with 2 spaces ("soft tab").
156   - New code preferably uses BSD-Style Bracing
157     if(foo)
158     {
159        bar();
160     }
161
162   Don't change brace styles unless you're working on the non BSD-Style
163    area (so we don't get spurious changes in line numbering).
164
165   Don't change indentation unless you're working on the badly indented
166    area (so we don't get spurious changes of large blocks of code).
167
168   Jedit is the recommended editor, a comment of this format should be
169   included in the top 10 lines of the file (see the embedded edit mode)
170---------------------------------------------------
171
172Unfortunately, given the endless nested "using dynamic function
173definitions as method arguments" the BSD bracing style makes the code
174impossible to read, IHMO.
175
176To make my life easier I've gone through and changed the style to:
177
178if (foo)
179  {
180  bar();
181  }
182
183So if you have a function definition as an argument as in:
184
185class.method( "foo",
186  function()
187    {
188    return bar;
189    });
190
191Which to my eye is alot easier to follow and less error prone.
192
193I tried Jedit. I can't stand Java apps and the editor is simply too
194slow. I use CRISP which unfortunately has some serious issues with
195tab to space conversions.
Note: See TracBrowser for help on using the repository browser.