added HOWTO text.

1 files changed, 110 insertions, 0 deletions

diff --git a/HOWTO b/HOWTO
new file mode 100644
index 0000000..ac3cb13
--- /dev/null
+++ b/HOWTO
@@ -0,0 +1,110 @@
+The purpose of this how-to is to help you transform the sofort
+project template into your own work-in-progress repository.
+
+So that all steps are concrete and fully defined, let us
+pretend that you would like to create a library and front-end
+utility named 'wonderer', and have accordingly chosen 'wndr'
+as your namespace prefix.
+
+
+OUTLINE
+-------
+step 1: clone.
+step 2: make this your own.
+step 3: create your first interface.
+
+
+step 1: clone
+-------------
+# ./sofort.sh -d $HOME/wonderer -p wonderer -n wndr
+# cd $HOME/wonderer
+# git init
+
+
+step 2: make this your own
+--------------------------
+* update the README file with a preliminary description
+  of your project.
+
+* update COPYING.WONDERER with your license of choice.
+
+* include/wonderer/wonderer.h: fix whitespace as needed.
+
+* src/wonderer.c: vermsg[]: replace git://midipix.org
+  with your own git host.
+
+* verify that all went well:
+
+# mkdir ../build && cd ../build
+# ../wonderer/configure && make
+
+* enjoy your skeleton by running bin/wonderer.
+
+* commit your changes (i.e. 'created skeleton').
+
+
+step 3: create your first interface
+-----------------------------------
+At the outset, adding a command-line interface involves
+the addition of an argv option record in conjunction
+with an option tag and a driver switch case.
+
+Unless a no-op, the above interface will correspond to
+either a flag in your common context structure (i.e.
+struct wndr_common_ctx), or an attribute in that structure,
+or both.
+
+Now let us practice all that while also looking at the two
+dummy interfaces which are part of sofort (note that these
+interfaces are *not* present in the generated project):
+
+* src/internal/wonderer_driver_impl.h: add a tag (see the
+  DUMMY and PROPERTY tags in the corresponding sofort file).
+
+* src/skin/wonderer_skin_default.c: add an argv option record;
+  if your option is associated with a finite set of values
+  (i.e. --fruit=apple|grape|orange) then you should take
+  advantage of the 'paradigm' member in struct argv_option
+  (see src/internal/argv/argv.h for the complete struct
+  definition).
+
+* src/driver/wndr_driver_ctx.c: add a switch case; depending
+  on the interface that you are adding, you will be either
+  setting a bit in one of the flag members of wndr_common_ctx
+  (in which case you should define a macro for that flag),
+  or assign the option value to an attribute in the above
+  context (in which case you should add an appropriate member
+  to the context structure). For the latter case, see the
+  handling of TAG_OUTPUT_DUMMY in the respective sofort file;
+  for the former, see the handling of TAG_OUTPUT_PROPERTY.
+
+* make use of the newly added flag/attribute in one or more
+  of your functions; remember to refer to your new source file
+  in project/common.src, and, assuming you would like to expose
+  it, add the function declaration to wonderer.h.
+
+* front-end utility (src/wonderer.c): if applicable, extend
+   wonderer_perform_unit_actions() so that it calls the above
+   (library) function as needed.
+
+
+what about attribution?
+-----------------------
+As far as I (Z. Gilboa) am concerned, no attribution
+beyond the copyright clause in argv.h is necessary.
+Should you wish to include a detailed attribution note
+with your project, however, you may find the following
+text useful:
+
+The starting point for this repository was a skeleton
+generated by 'sofort: portable software project template'
+(git://midipix.org/sofort, MIT licensed, see COPYING.SOFORT).
+
+The generated skeleton included the following elements:
++ the argv parser and usage screen generator (argv.h).
++ the build system (configure, Makefile.in, project/defs.mk).
++ the initial driver logic:
+  --> src/driver/namespace_driver_ctx.c
+  --> src/driver/namespace_unit_ctx.c
++ and initial input mapping logic:
+  --> src/logic/namespace_map_input.c