more docs fixes

[subdirmk.git] / subdirmk / README

diff --git a/subdirmk/README b/subdirmk/README
index e6da9eecd1f68b68ab930560236e802a741fb3cf..10117be3501d20c64cae09cb2827e06e4087b15f 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,7 +198,7 @@ empty string).
        it back before using &:include.
 
        Notably
-               STUFFSTUFF      =>      STUFF
+               STUFFSTUFF      =>      STUFFSTUFF
                \STUFF          =>      STUFF
                STUFF!&         set escape back to &
 
@@ -238,3 +238,67 @@ 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
+-----------------
+
+subdirmk is
+ Copyright 2019 Mark Wooding
+ Copyright 2019 Ian Jackson
+
+    subdirmk and its example is free software; you can redistribute it
+    and/or modify it under the terms of the GNU Library General Public
+    License as published by the Free Software Foundation; either
+    version 2 of the License, or (at your option) any later version.
+
+    This is distributed in the hope that it will be useful, but
+    WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Library General Public License for more details.
+
+    You should have received a copy of the GNU Library General Public
+    License along with this library as the file LGPL-2.
+    If not, see https://www.gnu.org/.
+
+Individual files generally contain the following tag in the copyright
+notice, instead of the full licence grant text:
+  SPDX-License-Identifier: LGPL-2.0-or-later
+As is conventional, this should be read as a licence grant.
+
+Contributions are accepted based on the git commit Signed-off-by
+convention, by which the contributors' certify their contributions
+according to the Developer Certificate of Origin version 1.1 - see
+the file DEVELOPER-CERTIFICATE.
+
+Where subdirmk is used by and incorporated into another project (eg
+via git subtree), the directory subdirmk/ is under GNU LGPL-2.0+, and
+the rest of the project are under that other project's licence(s).
+(The project's overall licence must be compatible with LGPL-2.0+.)