FYI: split documentation for public/private macros

[Alexandre Duret-Lutz]

I'm checking this in.

Index: ChangeLog
===================================================================
RCS file: /cvs/automake/automake/ChangeLog,v
retrieving revision 1.1765
diff -u -r1.1765 ChangeLog
--- ChangeLog   2002/02/19 20:18:00     1.1765
+++ ChangeLog   2002/02/19 20:59:57
@@ -1,5 +1,10 @@
 2002-02-19  Alexandre Duret-Lutz  <address@hidden>
 
+       * automake.texi (Macros): Split into ...
+       (Public Macros, Private Macros): ... these.
+
+2002-02-19  Alexandre Duret-Lutz  <address@hidden>
+
        * tests/insthook.test: Use sed instead of "tail +X".
 
 2002-02-18  Paul Eggert  <address@hidden>
Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.265
diff -u -r1.265 automake.texi
--- automake.texi       2002/02/17 22:12:38     1.265
+++ automake.texi       2002/02/19 21:00:26
@@ -1351,8 +1351,20 @@
 @node Macros, Extending aclocal, Invoking aclocal, configure
 @section Autoconf macros supplied with Automake
 
address@hidden consider generating this node automatically from m4 files.
+Automake ships with several Autoconf macros that you can use from your
address@hidden  When you use one of them it will be included by
address@hidden in @file{aclocal.m4}.
+
address@hidden
+* Public macros::               Macros that you can use.
+* Private macros::              Macros that you should not use.
address@hidden menu
 
address@hidden consider generating the following subsections automatically from 
m4 files.
+
address@hidden Public macros, Private macros, Macros, Macros
address@hidden Public macros
+
 @table @code
 @item AM_CONFIG_HEADER
 Automake will generate rules to automatically regenerate the config
@@ -1367,15 +1379,6 @@
 this should not be used unless you are familiar with the internals).
 @xref{Multilibs}.
 
address@hidden _AM_DEPENDENCIES
address@hidden AM_SET_DEPDIR
address@hidden AM_DEP_TRACK
address@hidden AM_OUTPUT_DEPENDENCY_COMMANDS
address@hidden FIXME: Consider not documenting these internal macros.
-These macros are used to implement automake's automatic dependency
-tracking scheme.  They are called automatically by automake when
-required, and there should be no need to invoke them manually.
-
 @item AM_C_PROTOTYPES
 Check to see if function prototypes are understood by the compiler.  If
 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
@@ -1441,12 +1444,6 @@
 @cvindex VERSION, prevent definition
 
 
address@hidden AM_MAKE_INCLUDE
address@hidden FIXME: Consider not documenting this internal macro.
-This macro is used to discover how the user's @code{make} handles
address@hidden statements.  This macro is automatically invoked when
-needed; there should be no need to invoke it manually.
-
 @item AM_PATH_LISPDIR
 Searches for the program @code{emacs}, and, if found, sets the output
 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
@@ -1488,18 +1485,6 @@
 GNU Compiler Collection.
 @cvindex AM_PROG_GCJ
 
address@hidden AM_PROG_INSTALL_STRIP
-This is used to find a version of @code{install} which can be used to
address@hidden a program at installation time.  This macro is
-automatically included when required.
-
address@hidden AM_SANITY_CHECK
address@hidden FIXME: Consider not documenting this internal macro.
-This checks to make sure that a file created in the build directory is
-newer than a file in the source directory.  This can fail on systems
-where the clock is set incorrectly.  This macro is automatically run
-from @code{AM_INIT_AUTOMAKE}.
-
 @item AM_SYS_POSIX_TERMIOS
 @cvindex am_cv_sys_posix_termios
 @cindex POSIX termios headers
@@ -1530,6 +1515,43 @@
 into @samp{LIBOBJS}.
 
 @end table
+
address@hidden Private macros,  , Public macros, Macros
address@hidden Private macros
+
+The following macros are private macros you should not call directly.
+They are called by the other public macros when appropriate.  Do not
+rely on them, as they might be changed in a future version.  Consider
+them as implementation details; or better, do not consider them at all:
+skip this section!
+
address@hidden @code
address@hidden _AM_DEPENDENCIES
address@hidden AM_SET_DEPDIR
address@hidden AM_DEP_TRACK
address@hidden AM_OUTPUT_DEPENDENCY_COMMANDS
+These macros are used to implement automake's automatic dependency
+tracking scheme.  They are called automatically by automake when
+required, and there should be no need to invoke them manually.
+
address@hidden AM_MAKE_INCLUDE
+This macro is used to discover how the user's @code{make} handles
address@hidden statements.  This macro is automatically invoked when
+needed; there should be no need to invoke it manually.
+
address@hidden AM_PROG_INSTALL_STRIP
+This is used to find a version of @code{install} which can be used to
address@hidden a program at installation time.  This macro is
+automatically included when required.
+
address@hidden AM_SANITY_CHECK
+This checks to make sure that a file created in the build directory is
+newer than a file in the source directory.  This can fail on systems
+where the clock is set incorrectly.  This macro is automatically run
+from @code{AM_INIT_AUTOMAKE}.
+
address@hidden table
+
 
 
 @node Extending aclocal,  , Macros, configure
Index: stamp-vti
===================================================================
RCS file: /cvs/automake/automake/stamp-vti,v
retrieving revision 1.164
diff -u -r1.164 stamp-vti
--- stamp-vti   2002/02/17 22:12:38     1.164
+++ stamp-vti   2002/02/19 21:00:26
@@ -1,4 +1,4 @@
address@hidden UPDATED 17 February 2002
address@hidden UPDATED 19 February 2002
 @set UPDATED-MONTH February 2002
 @set EDITION 1.5e
 @set VERSION 1.5e
Index: version.texi
===================================================================
RCS file: /cvs/automake/automake/version.texi,v
retrieving revision 1.237
diff -u -r1.237 version.texi
--- version.texi        2002/02/17 22:12:38     1.237
+++ version.texi        2002/02/19 21:00:26
@@ -1,4 +1,4 @@
address@hidden UPDATED 17 February 2002
address@hidden UPDATED 19 February 2002
 @set UPDATED-MONTH February 2002
 @set EDITION 1.5e
 @set VERSION 1.5e

-- 
Alexandre Duret-Lutz