more docs changes

[subdirmk.git] / subdirmk / README

diff --git a/subdirmk/README b/subdirmk/README
index d2b3c469e07986139a6e4dd9aa8c56c6ece2ff9d..95cdd69024b8ea194ab2d32d10d31c5857bf3a85 100644 (file)
--- a/subdirmk/README
+++ b/subdirmk/README
@@ -189,8 +189,8 @@ empty string).
 &!STUFF
        changes the escape sequence from & to literally STUFF
        STUFF may be any series of of non-whitespace characters,
-       and is terminated by EOL or lwsp.  STUFF and the lwsp
-       is discarded.
+       and is terminated by EOL or lwsp.  &!STUFF and the lwsp
+       are discarded.
 
        After this, write STUFF instead of &, everywhere.
        The effect is global and lasts until the next setting.
@@ -198,14 +198,13 @@ empty string).
        it back before using &:include.
 
        Notably
-               STUFFSTUFF      =>      STUFF
+               STUFFSTUFF      =>      STUFFSTUFF
                \STUFF          =>      STUFF
                STUFF!&         set escape back to &
 
 &TARGETS_things
-       Handled specially.  If mentioned, declares that
-       this subdirectory ought to have a target `things'.
-       (`all' if not specified).  The rule will be
+       Handled specially.  If mentioned, declares that this
+       subdir ought to have a target `things'.  The rule will be
                &/things:: $(&TARGETS_things)
 
        You may extend it by adding more :: rules for the target,
@@ -213,13 +212,14 @@ empty string).
                &TARGETS_check += & test-passed.stamp
 
        It is important to mention &TARGETS_things at least once in
-       the context of each applicable directory, because it arranges
-       that the *parent* will also have a `things' target which
-       recursively implies this directory's `things'.
+       the context of each applicable directory, because doing so
+       arranges that the *parent* will also have a `things' target
+       which recursively implies this directory's `things'.
 
        Must be spelled exactly &TARGETS_things.  &_TARGETS_things,
-       for example, does not work.  But mentioning it in a #-comment
-       *does* work because the & filter does not care about comments.
+       for example, is not magic.  But mentioning &TARGETS_things in
+       a #-comment *does* work because the & filter does not care
+       about comments.
 
        `all' is extra special: every directory has an `all'
        target, which corresponds to &TARGETS.
@@ -239,6 +239,33 @@ project) are best avoided.
 If you name your variables in ALL CAPS and your subdirectories in
 lower case with `-' rather than `_', there will be no confusion.
 
+Incorporating this into your project
+------------------------------------
+
+Use `git-subtree' to merge the subdirmk/ directory.  You may find it
+useful to symlink the DEVELOPER-CERTIFICATE file (git can store
+symlinks as symlinks - just `git add' the link).  And you probably
+want to mention the situation in your top-level COPYING.
+
+Symlink autogen.sh into your project toplevel.
+
+In your configure.ac, say
+
+  m4_include([subdirmk/subdirmk.ac])
+  SUBDIRMK_SUBDIRS([...list of subdirectories in relative syntax...])
+
+Write a Subdir.sd.mk in each directory.  The toplevel one should
+probably contain:
+
+  include subdirmk/usual.mk
+  include subdirmk/regen.mk
+
+Write a Perdir.sd.mk in the toplevel, if you want.  It should probably
+have:
+
+  &:include subdirmk/cdeps.sd.mk
+  &:include subdirmk/clean.sd.mk
+
 
 Legal information
 -----------------