Hi Karl,
thanks for the quick review!
* Karl Berry wrote on Fri, Mar 27, 2009 at 11:26:24PM CET:
>
> +* SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
>
> Probably a period after "vs", to match the @subsection name (and because
> this manual is (primarily?) in American English rather than British
> English).
What about this node in (texinfo)Node Line Requirements:
* Unfortunately, you cannot use periods, commas, colons or
parentheses within a node name; these confuse the Texinfo
processors. Perhaps this limitation will be removed some day, too.
In light of that, I haven't added a period here yet.
It seems to work with makeinfo 4.11.90 though.
Has this recently been fixed, and if yes, in which texinfo version?
Thanks. I don't want to have to require a very recent one.
> +* Non-configured Subdirectories:: Not even creating a @samp{Makefile}
>
> I think "Unconfigured" would be somewhat more idiomatic English, unless
> I'm missing some subtle distinction you're making.
Nope, fixed throughout the manual.
> +* The two Parts of Install:: Installing data and programs separately
>
> two should be capitalized.
Fixed.
> +...@node Subdirectories with AM_CONDITIONAL
> +...@subsection Conditional Subdirectories with @code{AM_CONDITIONAL}
>
> I am a fan of making the node name and sectioning name the same,
> wherever possible. Overall, this makes it easier for the reader. I
> think length of the node name is far less important.
But it will make the menus all ugly, no? Anyway, I like this too.
> So in this case (and the following similar cases) I would either have
> the "Conditional" in both names, or neither.
I've removed it from both now, as well as the next node.
> +...@node Required file ltmain.sh not found
> @subsubsection @samp{required file `./ltmain.sh' not found}
>
> Perhaps prepend the word "Error:" to both, and downcase "required" in
> the @node.
Again, what about colons which are disallowed in @node names, and
actually cause errors with this makeinfo version?
> @subsubsection Objects @samp{created with both libtool and without}
>
> Why @samp? Is this more error message text?
Yes.
> -...@subsection Third-party files
> +...@subheading Third-party files
>
> Files should be capitalized for consistency. Probably something to
> check throughout ...
Done in all headings and node names.
> +...@node Recommendations for Tools
> @subsection Recommendations for Tool Writers
>
> Again I'd make the two names the same. In this case, the two versions
> even mean different things :).
Indeed. Adjusted.
> +* Future Directions for Dependencies:: Languages Automake does not know
> ...
> +...@node Future Directions for Dependencies
> @subsection Future Directions for Automake's Dependency Tracking
>
> I think the @subsection should be made the same as @node here.
> "Automake's" doesn't buy anything.
Agreed.
> That's an unusual description in the menu, but interesting :).
| * Future Directions for Dependencies:: Languages Automake does not know
What is unusual about it?
> For example, one thing I don't like much with the result yet is that the
> introductory chapter has a section about two-part install, and its name
> is very similar to the section about two-part install later.
>
> Can you send me the whole master menu after applying changes above as
> you see fit, and I'll look again?
Thanks, here you go.
Cheers,
Ralf
@menu
* Introduction:: Automake's purpose
* Autotools Introduction:: An Introduction to the Autotools
* Generalities:: General ideas
* Examples:: Some example packages
* Invoking Automake:: Creating a Makefile.in
* configure:: Scanning configure.ac or configure.in
* Directories:: Declaring subdirectories
* Programs:: Building programs and libraries
* Other objects:: Other derived objects
* Other GNU Tools:: Other GNU Tools
* Documentation:: Building documentation
* Install:: What gets installed
* Clean:: What gets cleaned
* Dist:: What goes in a distribution
* Tests:: Support for test suites
* Rebuilding:: Automatic rebuilding of Makefile
* Options:: Changing Automake's behavior
* Miscellaneous:: Miscellaneous rules
* Include:: Including extra files in an Automake template
* Conditionals:: Conditionals
* Gnits:: The effect of @option{--gnu} and
@option{--gnits}
* Cygnus:: The effect of @option{--cygnus}
* Not Enough:: When Automake is not Enough
* Distributing:: Distributing the Makefile.in
* API versioning:: About compatibility between Automake versions
* Upgrading:: Upgrading to a Newer Automake Version
* FAQ:: Frequently Asked Questions
* History:: Notes about the history of Automake
* Copying This Manual:: How to make copies of this manual
* Indices:: Indices of variables, macros, and concepts
@detailmenu
--- The Detailed Node Listing ---
An Introduction to the Autotools
* GNU Build System:: Introducing the GNU Build System
* Use Cases:: Use Cases for the GNU Build System
* Why Autotools:: How Autotools Help
* Hello World:: A Small Hello World Package
Use Cases for the GNU Build System
* Basic Installation:: Common installation procedure
* Standard Targets:: A list of standard Makefile targets
* Standard Directory Variables:: A list of standard directory variables
* Standard Configuration Variables:: Using configuration variables
* config.site:: Using a config.site file
* VPATH Builds:: Parallel build trees
* Two-Part Install:: Installing data and programs separately
* Cross-Compilation:: Building for other architectures
* Renaming:: Renaming programs at install time
* DESTDIR:: Building binary packages with DESTDIR
* Preparing Distributions:: Rolling out tarballs
* Dependency Tracking:: Automatic dependency tracking
* Nested Packages:: The GNU Build Systems can be nested
A Small Hello World
* Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
* amhello Explained:: @file{configure.ac} and @file{Makefile.am}
explained
General ideas
* General Operation:: General operation of Automake
* Strictness:: Standards conformance checking
* Uniform:: The Uniform Naming Scheme
* Canonicalization:: How derived variables are named
* Length limitations:: Staying below the command line length limit
* User Variables:: Variables reserved for the user
* Auxiliary Programs:: Programs automake might require
Some example packages
* Complete:: A simple example, start to finish
* true:: Building true and false
Scanning @file{configure.ac}
* Requirements:: Configuration requirements
* Optional:: Other things Automake recognizes
* Invoking aclocal:: Auto-generating aclocal.m4
* Macros:: Autoconf macros supplied with Automake
Auto-generating aclocal.m4
* aclocal options:: Options supported by aclocal
* Macro search path:: How aclocal finds .m4 files
* Extending aclocal:: Writing your own aclocal macros
* Local Macros:: Organizing local macros
* Serials:: Serial lines in Autoconf macros
* Future of aclocal:: aclocal's scheduled death
Autoconf macros supplied with Automake
* Public macros:: Macros that you can use.
* Obsolete macros:: Macros that you should stop using.
* Private macros:: Macros that you should not use.
Directories
* Subdirectories:: Building subdirectories recursively
* Conditional Subdirectories:: Conditionally not building directories
* Alternative:: Subdirectories without recursion
* Subpackages:: Nesting packages
Conditional Subdirectories
* SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
* Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
* Subdirectories with AC_SUBST:: Another way for conditional recursion
* Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
Building Programs and Libraries
* A Program:: Building a program
* A Library:: Building a library
* A Shared Library:: Building a Libtool library
* Program and Library Variables:: Variables controlling program and
library builds
* Default _SOURCES:: Default source files
* LIBOBJS:: Special handling for LIBOBJS and ALLOCA
* Program variables:: Variables used when building a program
* Yacc and Lex:: Yacc and Lex support
* C++ Support:: Compiling C++ sources
* Objective C Support:: Compiling Objective C sources
* Unified Parallel C Support:: Compiling Unified Parallel C sources
* Assembly Support:: Compiling assembly sources
* Fortran 77 Support:: Compiling Fortran 77 sources
* Fortran 9x Support:: Compiling Fortran 9x sources
* Java Support:: Compiling Java sources
* Support for Other Languages:: Compiling other languages
* ANSI:: Automatic de-ANSI-fication (obsolete)
* Dependencies:: Automatic dependency tracking
* EXEEXT:: Support for executable extensions
Building a program
* Program Sources:: Defining program sources
* Linking:: Linking with libraries or extra objects
* Conditional Sources:: Handling conditional sources
* Conditional Programs:: Building program conditionally
Building a Shared Library
* Libtool Concept:: Introducing Libtool
* Libtool Libraries:: Declaring Libtool Libraries
* Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
* Conditional Libtool Sources:: Choosing Library Sources Conditionally
* Libtool Convenience Libraries:: Building Convenience Libtool Libraries
* Libtool Modules:: Building Libtool Modules
* Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
* LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
* Libtool Issues:: Common Issues Related to Libtool's Use
Fortran 77 Support
* Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
* Compiling Fortran 77 Files:: Compiling Fortran 77 sources
* Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
Mixing Fortran 77 With C and C++
* How the Linker is Chosen:: Automatic linker selection
Fortran 9x Support
* Compiling Fortran 9x Files:: Compiling Fortran 9x sources
Other Derived Objects
* Scripts:: Executable scripts
* Headers:: Header files
* Data:: Architecture-independent data files
* Sources:: Derived sources
Built sources
* Built sources example:: Several ways to handle built sources.
Other GNU Tools
* Emacs Lisp:: Emacs Lisp
* gettext:: Gettext
* Libtool:: Libtool
* Java:: Java
* Python:: Python
Building documentation
* Texinfo:: Texinfo
* Man pages:: Man pages
Installation
* Basics of Installation:: What gets installed where
* The Two Parts of Install:: Installing data and programs separately
* Extending Installation:: Adding your own rules for installation
* Staged Installs:: Installation in a temporary location
* Install Rules for the User:: Useful additional rules
Distribution
* Basics of Distribution:: Files distributed by default
* Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
* The dist Hook:: A target for last-minute distribution changes
* Checking the Distribution:: @samp{make distcheck} explained
* The Types of Distributions:: A variety of formats and compression methods
Support for Test Suites
* Simple Tests:: Listing programs and scripts in @code{TESTS}
* Simple Tests using parallel-tests:: More powerful test driver
* DejaGnu Tests:: Interfacing with the external testing framework
* Install Tests:: Running tests on installed packages
Miscellaneous Rules
* Tags:: Interfacing to etags and mkid
* Suffixes:: Handling new file extensions
* Multilibs:: Support for multilibs.
Conditionals
* Usage of Conditionals:: Declaring conditional content
* Limits of Conditionals:: Enclosing complete statements
When Automake Isn't Enough
* Extending:: Adding new rules or overriding existing ones.
* Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
Frequently Asked Questions about Automake
* CVS:: CVS and generated files
* maintainer-mode:: missing and AM_MAINTAINER_MODE
* wildcards:: Why doesn't Automake support wildcards?
* Limitations on File Names:: Limitations on source and installed file names
* distcleancheck:: Files left in build directory after distclean
* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
* renamed objects:: Why are object files sometimes renamed?
* Per-Object Flags:: How to simulate per-object flags?
* Multiple Outputs:: Writing rules for tools with many output files
* Hard-Coded Install Paths:: Installing to Hard-Coded Locations
History of Automake
* Timeline:: The Automake story.
* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
* Releases:: Statistics about Automake Releases
Dependency Tracking Evolution
* First Take on Dependencies:: Precomputed dependency tracking
* Dependencies As Side Effects:: Update at developer compile time
* Dependencies for the User:: Update at user compile time
* Techniques for Dependencies:: Alternative approaches
* Recommendations for Tool Writers:: What tool writers can do to help
* Future Directions for Dependencies:: Languages Automake does not know
Copying This Manual
* GNU Free Documentation License:: License for copying this manual
Indices
* Macro Index:: Index of Autoconf macros
* Variable Index:: Index of Makefile variables
* General Index:: General index
@end detailmenu
@end menu
