[MERGE] Add a brief Portability section to HACKING, build HACKING.htm from 'make docs'.

[John Arbash Meinel]

Andrew Bennetts wrote:
> Somewhat related to this morning's discussion about documentation, although I
> actually wrote this on the train last night...
> 
> This bundle adds a brief section on Portability to HACKING (much more could be
> said, but you have to start somewhere).  It also builds doc/HACKING.htm when you
> run "make docs", because I found myself wanting to look at the processed HTML to
> get a better feel for what's already in HACKING, and where the new section would
> best fit.
> 
> -Andrew.
> 
> 
> 
> ------------------------------------------------------------------------
> 
> # Bazaar revision bundle v0.9
> #
> # message:
> #   Add a brief section on portability to HACKING.
> # committer: Andrew Bennetts <andrew.bennetts at canonical.com>
> # date: Wed 2007-04-11 20:46:19.743000031 +1000
> 
> === modified file HACKING
> --- HACKING
> +++ HACKING
> @@ -589,6 +589,17 @@
>  valid characters are generated where possible.
>  
>  
> +Portability Tips
> +================
> +
> +The ``bzrlib.osutils`` module has many useful helper functions, including
> +some more portable variants of functions in the standard library.
> +
> +In particular, don't use ``shutil.rmtree`` unless it's acceptable for it
> +to fail on Windows if some files are readonly or still open elsewhere.
> +Use ``bzrlib.osutils.rmtree`` instead.
> +
> +

^- I would have rather broken this up a bit (putting the osutils warning
into a subsection).

There is a lot of information that could be said about functions in
osutils. I'm guessing it should be in a separate document, though,
because there is a lot there. (all of the pathjoin, abspath, etc
functions, even mkstemp)

But I think this is still a step forward.

John
=:->