twingle/doc debugging.txt,1.1.1.1,1.2

Update of /cvs/root/twingle/doc
In directory alpha.oscom.org:/tmp/cvs-serv11492

Modified Files:
	debugging.txt 
Log Message:
Lots of material added.


Index: debugging.txt
===================================================================
RCS file: /cvs/root/twingle/doc/debugging.txt,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** debugging.txt	5 Mar 2003 19:30:31 -0000	1.1.1.1
--- debugging.txt	6 Mar 2003 10:50:55 -0000	1.2
***************
*** 7,21 ****
    trials-and-errors.
  
! nightly builds turn on chrome warnings
! dump and turn on dump output
! dom inspector and find
! venkman and preference
! tcpwatch
! debug attribute on boxes
! dumping rdf
! jsconsole
  
  
! common mistakes
  
!   o namespaces
--- 7,161 ----
    trials-and-errors.
  
! General
! 
!   Start small
  
+     The number one lesson I've learned in Mozilla is: start small and
+     only add one thing at a time.  Literally, like, one element at a
+     time.
  
! XUL/JS Debugging
  
!   Fortunately, debugging XUL and JavaScript is pretty easy.  Here are
!   some tips.
! 
!   Avoid restart
! 
!     Restarting your browser on each change sucks.  That's why you
!     don't have to.  If you have a nightly build or a beta, there is a
!     preference you can set that lets you avoid this.
!     "Preferences->Debug->Networking", select "Disable XUL Cache".
!     Meaning, make sure it is checked.
! 
!     **Note: RDF doesn't reload !!** This point is discussed below.
! 
!   Enable dump
! 
!     Alert boxes suck.  Instead, you can put dump statements in your
!     code that send text to stdout.
! 
!     To enable this: "Preferences->Debug" and select "Enable JavaScript
!     dump() output".  This lets you put a line in your scripts such as:
! 
!       var goober = document.getElementById("goober").value;
!       dump("\ngoober is " + goober);
! 
!   JavaScript Console
! 
!     Most of the time, Mozilla will tell you where your error is, you
!     just have to know where to look.  That place is the JavaScript
!     console.  "Tools->Web Development->JavaScript Console".
! 
!     Alas, the value of these exception messages goes down when you
!     have or trigger an XPCOM error.
! 
!   Use the debugger
! 
!     Gosh, having Venkman (the Mozilla graphical debugger) makes all
!     the difference in the world.  No more alerts or dumps.  However,
!     you have to make one small change, or else you can't debug XUL
!     stuff.
! 
!     Open Venkman with "Tools->Web Development->JavaScript Debugger".
!     In the Venkman "Debug" menu, unselect the (mislabeled) last menu
!     entry of "Exclude browser files".  In this case, "browser files"
!     means your XUL chrome app!  We don't want to exclude that!
! 
!     By the way, Mozilla doesn't ship with the newest version on
!     Venkman.  You can get this, plus some links to *very* good
!     tutorials for Venkman, from:
! 
!       http://www.hacksrus.com/~ginda/venkman/
! 
!   DOM Inspector
! 
!     This is another really useful tool.  Look in "Tools->Web
!     Development->DOM Inspector".  In the input box at the top, enter
!     "chrome://twingle/content" (without the quote marks).
! 
!     In the bottom you'll see Twingle.  Now, click on the icon to the
!     left of the binoculars, in the top left.  This icon has a cursor
!     arrow in it and the tooltiptext says "Find a node to inspect by
!     clicking on it".  Indeed.  Click on this button, then click
!     somewhere in Twingle in the bottom pane.  You'll be taken to that
!     node and you can look at the inspector.
! 
!     This is really helpful when debugging the output from RDF
!     templates.  The DOM inspector is also useful as a way to avoid
!     reload without running in a full browser window.  Just leave the
!     DOM Inspector always running, click in the input box, and hit
!     enter to reload Twingle.
! 
!   Box debugging
! 
!     If you get confused about box layout (CSS boxes, that is) or think
!     something is missing, you can add debug="true" to the window
!     element in twingle.xul.  This will draw a border around every
!     block element in Twingle.
! 
! RDF
! 
!   Debugging RDF is very, very frustrating.  If you make the slightest
!   mistake, you simply don't see anything on the screen.  And since
!   there are no visual tools like the DOM Inspector, you are left to
!   figure it out for yourself.  Also, the RDF parser doesn't report
!   errors anywhere.  Nice!
! 
!   Here are some tips on what can go wrong.
! 
!   Not well-formed XML
! 
!     You can stare at your RDF file for hours and not realize you
!     forgot to close a tag.  Either use some XML parser, or better yet,
!     put your RDF into the RDF validator at W3C:
! 
!       http://www.w3.org/RDF/Validator/
! 
!     Note that Mozilla uses some parts of RDF that are deprecated, so
!     ignore those warnings.
! 
!   Namespace mismatch
! 
!     This is a very common error.  Your RDF file, your templates, and
!     your JavaScript all need to use the same namespaces on properties.
!     You make a small change in one place and forget to apply it
!     elsewhere, and POOF!  No more stuff appears in the tree.
! 
!   Dumping RDF
! 
!     This is certainly the number one technique once you get started,
!     especially when retrieving server-generated RDF.  There are
!     various techniques for serializing an RDF datasource and printing
!     it somewhere.  (Twingle will have convenience functions for this.)
! 
!     The result: you can look at what the RDF service thinks is the
!     actual model for your data, after parsing.  You'll likely find
!     that there are no XML elements at all in the output, because you
!     make a mistake in the XML.
! 
!     You'll also discover the coolness of the "Model is not syntax"
!     part of RDF, because the stuff Mozilla spits out will look nothing
!     at all like what you gave it.  But it is logically the same model.
! 
!   Content type
! 
!     The server must send an HTTP header for content type that is the
!     right header value.  If not, Mozilla will silently not parse it.
! 
!   RDF reload
! 
!     RDF datasources aren't easily reloaded.  Thus, you can't change a
!     file on disk and simply do a browser reload.  Instead, you have to
!     do some JavaScript tricks.  Twingle will provide these.
! 
! Network
! 
!   tcpwatch
! 
!     If you need to see what is happening between you and the server, I
!     recommend tcpwatch from my friend Shane Hathaway:
! 
!       http://hathaway.freezope.org/Software/TCPWatch
! 
!     This is a very easy-to-use Python application that acts as a port
!     forwarder.  Uses Tk or a console interface.