Updated the readme to describe all the new features.

1 files changed, 40 insertions, 16 deletions

diff --git a/readme.creole b/readme.creole
index 148e6d3..673e7fb 100644
--- a/readme.creole
+++ b/readme.creole
@@ -2,17 +2,33 @@
 
 == Prerequisites
 
+* OpenSCAD snapshot > 2014.11.05
+** Used to compile OpenSCAD source files to STL.
+** It is recommended to a recent development snapshot, e.g. version 2014.11.05 or later.
+	** The current release version (2014.03) generates invalid dependency information if the path to the project contains spaces or other characters that need to be treated specially in a makefile and also has trouble with 2D shapes containing holes. The current development version solves these problems.
+
 * Inkscape
 ** Used to export DXF files to SVG.
+** Recommended to be used to edit SVG files, especially if its necessary to create multiple layers and import them separately in OpenSCAD.
+
+* Python 2.7
+** Used for to run the plugin that exports DXF to SVG and to run scripts that wrap the OpenSCAD command line tool and work around problems with generation of dependency information of OpenSCAD.
+** Should already be installed as a dependency to Inkscape. The most recent version of Python 2.7 is recommended.
+
 
-* OpenSCAD
-** The currently newest version (2014.03) has trouble with 2D shapes containing holes. The current development version solves these problems.
-** It is assumed that the 'openscad' binary is on $PATH.
+=== Explicitly specifying paths to binaries
 
-If any of the required binaries ('inkscape' for Inkscape and 'openscad' for OpenSCAD) is not available on $PATH, paths to these binaries can be configured by creating a file called 'config.mk' in the same directory as the makefile. There, the variables 'OPENSCAD' and 'INKSCAPE' can be set to the appropriate paths like this:
+If any of the required binaries is not available on `$PATH` or different versions should be used, the paths to these binaries can be configured by creating a file called 'config.mk' in the same directory as the makefile. There, variables can be set to the paths to these binaries (or to a different binary name which can be found on `$PATH`), like shown in the following example:
 
 {{{
+# Path to the OpenSCAD binary
 OPENSCAD := /Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD
+
+# Path to the Inkscape binary
+INKSCAPE := /opt/local/bin/inkscape
+
+# Path to the Python 2.7 binary
+PYTHON := /opt/local/bin/python2.7
 }}}
 
 
@@ -26,7 +42,20 @@ Any file whose name ends in `.svg` may be used from an OpenSCAD file like this:
 import("file.dxf");
 }}}
 
-The makefile will automatically convert the SVG file to a DXF file.
+The makefile will automatically convert the SVG file to a DXF file when building the project. If Inkscape is used to edit the SVG file, multiple layers can be created which can then be imported individually:
+
+{{{
+import("file.dxf", "background");
+}}}
+
+The DXF export supports all shapes supported by Inkscape (e.g. rectangles, circles, paths, spiro lines, text, ...). Before the object are exported, all objects are converted to paths and combined using the union operation. Then, the resulting paths are converted to line segments which closely follow the curved parts of the path [0]. The resulting line segments are exported to DXF and combined to the original shapes when imported in OpenSCAD. For these transformations to work, the objects need to be placed in Inkscape layers.
+
+OpenSCAD itself does not defined in which unit any numbers are interpreted [1]. Inkscape OTOH allows the used to defined a document wide unit as well as using different units when specifying the size and position of shapes. When exporting the SVG document using Inkscape, all numbers are converted to the unit specified under ''General'' in Inkscape's ''Document Properties'' dialog. These numbers are then used when writing the DXF document and these are the numeric sizes and positions that OpenSCAD will see.
+
+DXF and OpenSCAD both use a right-handed coordinate system (the Y axis runs up when the X-axis runs to the right). While SVG uses a left-handed coordinate system (the Y axis runs down if the same orientation is used). Inkscape, surprisingly also uses a right-handed coordinate system. The DXF export script honors that and places assumes the origin of the document in the lower left corner when exporting the document.
+
+[0]: Controlling how fine curved parts are subdivided currently cannot controlled without editing the DXF export scripts. This is a pending issue.
+[1]: Although millimeters seems to be the predominant unit.
 
 
 === OpenSCAD files
@@ -38,30 +67,25 @@ include <filename>
 use <filename>
 }}}
 
-Please see the [http://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version|manual] for details.
+OpenSCAD files may be compiled to STL and used from other OpenSCAD files at the same time. Please see the [http://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version|manual] for details and on how to use OpenSCAD in general.
 
 
 == Generating Source files
 
-This template allows files to be generated automatically. Currently supported for inclusion in the build proess are OpenSCAD and SVG files. This works by editing the `generate_sources.sh` script, which is run by the Makefile was changed.
+This template includes support automatically generated source files. Currently supported for inclusion in the build process are OpenSCAD and SVG files. This works by editing the `generate_sources.sh` script.
 
-The script should call the function `generate_file()` once for each file which should be generated. The first argument to the function should be the name of the file to be generated, the remaining arguments a command, which when run should output the file's content to standard output. How this function is called is up to the scrtip and may e.g. be done from a `for` loop or while iterating over a set of other source files.
+The script defines a function `generate_file()`, which should be called in the remainder of the script once for each file which should be generated. The first argument to the function is be the name of the file to be generated, the remaining arguments a command, which when run should output the file's content to standard output. How the function  `generate_file()` is called is up to the script and may e.g. be done from a `for` loop or while iterating over a set of other source files.
 
 
 == Compiling
 
-To compile the whole project, run `make` from the directory in which this readme is. This will process all necessary SVG files and produce an STL file for each OpenSCAD source file. Individual files may be created or updated by passing their names to the make command, as ussual.
+To compile the whole project, run `make` from the directory in which this readme is. This will generate all sources files, if any, process all SVG files and produce an STL file for each OpenSCAD source file whose name does not start with `_`. Individual files may be created or updated by passing their names to the make command, as usual.
 
 To remove all generated files, run `make clean`.
 
 
 === Dependency tracking
 
-OpenSCAD actually does have the ability to produce dependency files which can be read by `make` but does this in a way that makes using them in a project with multiple directories near-impossible. Because of this, dependencies between files are generated from a few assumptions based on simple naming-conventions:
+OpenSCAD has the ability to write dependency files which record all files used while producing an STL file. These dependency files can be read by `make`. This ability is used to only recompile necessary files when running make.
 
-* Only files in the `src` directory are compiled.
-* Each generated STL file solely depends on the OpenSCAD file with the same name.
-* Each generated DXF files solely depends on the SVG files with the same name.
-* Each OpenSCAD file depends whose name does not begin with `_` depends on two sets of files:
-** All OpenSCAD files in the same directory whose names do begin with `_`.
-** All DXF files in the same directory.
+This same mechanism is currently not used for converting SVG files referring to other files or for the script used to generate source files. There, if other file are used in the process, the source file tracked by the makefile (the main SVG files or the files `generate_sources.sh` in case of generated sources) needs to be manually updated by running `touch` on the file before calling `make`.