lots of updating

doc/development/notes/apps.txt

@@ -16,13 +16,14 @@ App Commonality
 The following notes apply to all apps:
 
 * The apps should have a common support/utilities library for processing
-  command line arguments, showing version information, etc.
+  command line arguments, showing version information, etc. -- describe
+  boost program_options, and Application/AppSupport classes
 
 * Input format detection should reside in the app, not in the library.
   There will be no equivalent meta GDALOpen-like function to do this work
   for you, as it is too expensive and too easy to screw up.
 
-
+* describe common switches: --version, --help, --verbose
 
 pc2pc
 =====
@@ -54,19 +55,27 @@ The dump should go the stdout, but options should be provided to dump to
 XML or similar, where it makes sense to do so.
 
 
+pcpipeline
+==========
+
+[tbd]
+
 
 pcview
 ======
 
-A simple 3D viewer for point clouds.  Strictly speaking, not a command-line
-app.  Will be a Windows-only thing (WPF + DirectX), unless someone else
-wants to do something too.
+A simple 3D viewer for point clouds, largely for development and testing
+as opposed to something for "rea" use.  Uses OpenGL; works under Windows,
+should work under Unix too.
+
 
 
 
 pcindex
 =======
 
+(future)
+
 Creates a serialized spatial index for a point cloud. First pass at this 
 is to repurpose liblas::Index which supports serialization.
 
@@ -75,12 +84,16 @@ is to repurpose liblas::Index which supports serialization.
 pcmerge
 =======
 
+(future -- likely to be part of pc2pc)
+
 Merges multiple files together.  (This is also known as mosacking.)
 
 
 
 pctile
 ======
 
+(future -- likely to be part of pc2pc)
+
 Chops one file up into multiple files.  This could be the liblas::Chipper, 
 leaf nodes of an index like an R-tree, or a simple quadtree build.

doc/development/notes/bindings.txt

@@ -9,6 +9,12 @@ Bindings
 We will support SWIG bindings for languages like Python and C#.  
 
 We will avoid things that will make SWIG's life difficult, such as multiple
-inheritance.
+inheritance and templates.
 
+SWIG doesn't support operator overloading, so provide alternative, "regular"
+functions that do the same thing, e.g. equals() for oper== and oper!=.
 
+In the bindings, we will not attempt to provide every member function for
+the classes, nor indeed will we necessarily provide bindings for all the
+classes.  If you really need the "full" functionality of PDAL, you should
+probably be using the native C++ interfaces.

doc/development/notes/boost.txt

@@ -0,0 +1,18 @@
+.. _boost:
+
+===================
+PDAL's Use of Boost
+===================
+
+
+* we use boost
+
+* don't reinvent the wheel, use a boost package
+
+* ptrees
+
+* program_options
+
+* unit test
+
+* other packages we use

doc/development/notes/building.txt

@@ -0,0 +1,84 @@
+.. _building:
+
+========
+Building
+========
+
+This Note contains some notes on project dependencies, configurations,
+building, etc.
+
+
+Endianness
+==========
+
+PDAL will not be supporting big-endian (BE) platforms at this time.  We
+recognize it would be good to do so, since endianness ports always seem to
+shake out twiddly little bugs, but we don't have ready access a BE
+development box.
+
+Where you are writing endian-sensitive code, you should comment it loudly
+so future maintainers will know where to go to add BE support.
+
+
+Project Dependencies - 3rd Party Libs
+=====================================
+
+PDAL will use these libraries:
+
+
+* Boost - for C++ library needs, such as streams or parsers (required)
+
+* libxml2 - Schema description, validation, and serialization (required)
+
+* GDAL - for spatial reference support (and rasterization) (optional)
+
+* libLAS - for LAS (compressed if available to libLAS) support. (optional)
+
+* MrSID - for LizardTech's MG4 lidar format (optional)
+
+* Oracle - OCI (optional)
+
+* libspatialindex - Rtree support, maybe quadtree if someone implements it for libspatialindex (optional)
+
+* *others?*
+
+Some of these libraries may be required (such as Boost).
+
+
+Project Dependencies - Builds/Infrastructure
+============================================
+
+To develop and build PDAL, we'll be using these tools:
+
+* Sphinx and rst2pdf - for docs
+
+* CMake - for generating makefiles
+
+* Python - for miscellaneous scripting needs
+
+* *others?*
+
+
+Buildbot
+========
+
+A buildbot will eventually be set up to prevent builds from breaking and to
+keep the unit tests passing.
+
+
+Platforms
+=========
+
+We will support these platforms initially, corresponding to what the
+developers are using regularly:
+
+* Windows - VS2010 (32- and 64-bit) - 2008 32-bit
+
+* Linux - gcc 4.x+
+
+* Mac - gcc 4.0.1+
+
+By virtue of CMake, other platforms may be supported such as VS 2008 or 
+Solaris, but we aren't targeting those specifically.
+
+

doc/development/notes/coding-conventions.txt

@@ -16,11 +16,11 @@ Source Formatting
 
 We use astyle (http://astyle.sourceforge.net) as a tool to reformat C++
 source code files in a consistent fashion.  The file astylerc, at the top
-of the hg repo, contains the default settings we use.
+of the github repo, contains the default settings we use.
 
 Our conventions are:
 
-* LF endings, not CRLF
+* LF endings (unix style), not CRLF (windows style)
 
 * spaces, not tabs
 
@@ -35,6 +35,10 @@ Our conventions are:
        foo();
     }
 
+* copyright header on every file 
+
+* two spaces between major units, e.g. function bodies
+
 
 Naming Conventions
 ==================
@@ -58,14 +62,25 @@ Other Conventions
   variables
 
 * Surround all code with "namespace pdal {...}"; where justifiable, you 
-  may introduce a nested namespace.  Keep non-public names in the 
-  pdal::detail\:: space.
+  may introduce a nested namespace.
 
 * Use exceptions for exceptional events that are not going to be handled 
   directly within the context of where the event occurs.  Avoid status
   codes.  See exceptions.hpp for a set of pdal-specific exception types 
-  you may throw.
+  you may throw.  (See Note on error handling)
+
+* Describe use of "debug" and "verbose" settings.
+
+* Don't put member function bodies in the class declaration in the
+  header file, unless clearly justified for performance reasons.
+  Use the "inline" keyword in these cases(?).
+
+* Use const.
+
+* Don't put "using" declarations in headers.
 
+* Document all public (and protected) member functions using
+  doxygen markup.
 
 Layout/Organization of Source Tree
 ==================================

doc/development/notes/core-classes.txt

@@ -4,14 +4,52 @@
 Core Classes
 ============
 
-This Notes describes the core classes used by PDAL.
+This Notes describes the core classes used by PDAL, such as Range and
+Dimension, that are not described in Notes of their own.
+
+The classes describing the Pipeline/Stage system, howver, are
+described in a different Note.
+
+* Bounds
+
+* Color
+
+* Dimension, DimensionLayout
+
+* pdal_error
+
+* FileUtils
+
+* Filter, FilterIterator
+
+* MetadataRecord
+
+* MultiFilter, MultiFilterIterator
+
+* Options
+
+* PipelineManager, PipelineReader, PipelineWriter
+
+* PointBuffer
 
 * Range
 
-* Dimension
+* Reader, ReaderIterator
+
+* Schema, SchemaLayout
+
+* SpatialReference
+
+* Stage, StageBase, StageFactory, StageIterator
+
+* StreamManager
+
+* UserCallback
 
-* ...
+* Utils
 
-[tbd]
+* Vector
 
+* Writer
 
+* XMLSchema

doc/development/notes/docs.txt

@@ -4,32 +4,47 @@
 Docs
 ====
 
-There will be two kinds of documentation: API docs, and Everything Else.
+PDAL comes with a few different types of documentation:
+
+* the API reference documentation
+
+* the command line applications user manual
+
+* Tutorials and Examples
+
+* the Developer Notes
+
+This documentation is all provided on the website, via Sphinx.
 
 
 API Documentation
 =================
 
-The API docs will be autogenerated by **[doxygen or something]** from the 
+The API docs will be autogenerated by doxygen from the 
 header files.
 
-**[need to provide info on what syntax to use]**
+See the Note on Coding Conventions for information on what syntax to use
+for this.
+
 
-These will be available on the website.
+Command Line Apps
+=================
 
+The command line apps are documented via Sphinx using RST markup.
 
-Everything Else
+
+Tutorials and Examples
+======================
+
+Similar to how libLAS was done, the PDAL website will contain a set of simple
+code fragments that show how to do basic operations using PDAL.
+
+This documentation will also include sample Python/C# code.
+
+
+Developer Notes
 ===============
-
-All the other documentation will be in the form of RST files, e.g. these 
-Notes, which will be autogenerated into web page content.  Documentation
-content will include:
-
-* usage guide for the command-line apps
-
-* developer-oriented information like PDAL architecture and core classes
-
-* information about specific file format readers and writers, e.g. details
-  on what versions of the LAS spec is supported
-
-* **[...?]**
+
+All development-related documentation, such as design notes, coding
+conventions, and so on, will be documented in a Development Notes
+section of the PDAL website, via Sphinx using RST markup.