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://localhost
  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