Re: sections without nodes in automake manual?

[Ralf Wildenhues]

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.

>     address@hidden Subdirectories with AM_CONDITIONAL
>     address@hidden 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.

>     address@hidden 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.

>     address@hidden Third-party files
>     address@hidden Third-party files
> 
> Files should be capitalized for consistency.  Probably something to
> check throughout ...

Done in all headings and node names.

>     address@hidden 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
>     ...
>     address@hidden 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