Improved overall clarity of text and added warning about TextEdit deleting CVS folder...

diff --git a/OS X Package Builder HOWTO.txt b/OS X Package Builder HOWTO.txt
index a22326b..0ab62e1 100644 (file)
--- a/OS X Package Builder HOWTO.txt
+++ b/OS X Package Builder HOWTO.txt
@@ -18,7 +18,10 @@ OVERVIEW OF STEPS
 
 1. Build the privoxy binary
 1.1 Consider whether to use external or bundled PCRE.
+1.2 Builds for the Sourceforge Privoxy project release set
 2. Construct the package contents hierarchy
+2.1 Update the supporting documentation for the release
+2.2 Bring together all the contents ready to package
 3. Build the package
 
 
@@ -28,15 +31,19 @@ DETAILS
 
 Use privoxy-create.sh (run via sudo) to create the privoxy group and user; these are a prerequisite for the build process.
 
-Use build.sh to build a privoxy binary for the desired (range of) platform(s) and to control whether or not to compile against the external PCRE library (see 1.1 below). The simplest usage is:
+Use build.sh to build a privoxy binary for the desired (range of) platform(s) and to control whether or not to compile against the external PCRE library (see 1.1 below). The most compatible usage is:
 
 ./build.sh leopardupwards
 
-which will build a Universal binary containing targets for PPC, i386 and x86_64 processor architectures that'll run on all Macintosh OS X versions from 10.5 (Leopard) and upwards. If however you would prefer to, for example, build a binary that runs solely on 64 bit Intel processors, you could instead use:
+which will build a Universal binary containing targets for PPC, i386 and x86_64 processor architectures that'll run on all Macintosh OS X versions from 10.5 (Leopard) and upwards. The disadvantage of bundling multiple processor architectures is that the build is consequently limited to using the bundled PCRE implementation, which is a Bad Idea™ (see section 1.1 for details).
+
+The most common usage therefore would be as follows:
+
+./build.sh snowleopardx64 -pcre
 
-./build.sh snowleopardx64
+which will build a binary targetting only x86_64 processors (note that OS X has supported only x86_64 since Snow Leopard).
 
-Running build.sh without supplying any parameters will cause it to list all the possible options.
+Running build.sh without supplying any parameters will cause it to list all the possible options, should you have an alternative target requirement.
 
 
 1.1 Consider whether to use external or bundled PCRE.
@@ -69,10 +76,21 @@ Note that in order to build each version, the pcre library fileset must be chang
 
 2. Construct the package contents hierarchy
 
-Use constructPkgContent.sh to build the hierarchy of folders and files necessary for building the package. This will construct a new folder named 'pkg content' and copy in the binary, documentation and supporting files. If you are bundling an external PCRE fileset (i.e. if you built privoxy to use an external PCRE library), use the optional switch -pcre to instruct constructPkgContent.sh to include the libpcre fileset, which it will source from the standard installed location on the build machine (/usr/local/lib).
+This comprises two steps:
+- ensuring the supporting documentation is updated for the release
+- using the supplied script to bring all the package contents together
+
+2.1 Update the supporting documentation for the release
+
+The file 'pkg resources/interface texts/ReadMe.txt' is displayed on one of the installer screens; it will need to be edited to give a precis of what this release of Privoxy brings. This can be distilled from the README for the latest Privoxy project release.
+
+If there is any late-breaking or important info, it should be added to 'pkg content skeleton/Applications/Privoxy/readme.rtfd. This file MUST be edited with TextEdit, however BEWARE! TextEdit rtfd documents are actually a folder with files within (right-click and choose 'Show package contents' to see within). Inside you'll see a CVS folder that the cvs file storage repository software uses to keep track of that folder's files. If you save an .rtfd document in TextEdit, it will delete the CVS folder! The workaround then is to move that folder elsewhere, make the necessary file edits and save, close TextEdit and then move the folder back in place before committing the files back with cvs.
+
+2.2 Bring together all the contents ready to package
 
-Once this is done, the file 'pkg resources/interface texts/ReadMe.txt' will need to be edited to give a precis of what this release of Privoxy brings. This can be distilled from the README for the latest Privoxy project release.
+Use constructPkgContent.sh to build the hierarchy of folders and files necessary for building the package. This will construct a new folder named 'pkg content' and copy in the binary, documentation and supporting files. If you are bundling an external PCRE fileset (i.e. if you built privoxy to use an external PCRE library), use the optional switch -pcre to instruct constructPkgContent.sh to include the libpcre fileset, which it will source from the standard installed location on the build machine (/usr/local/lib). The typical command line then is:
 
+./constructPkgContent.sh -pcre
 
 
 3. Build the package