bug-automake
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: sections without nodes in automake manual?


From: Karl Berry
Subject: Re: sections without nodes in automake manual?
Date: Fri, 27 Mar 2009 17:26:24 -0500

    I'm not sure I like info files where each 5-line subsubsection is a
    separate node

Sure.  Splitting/lumping is always a judgement call.

    +* 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).

    +* 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.

    +* The two Parts of Install::    Installing data and programs separately

two should be capitalized.

    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.

So in this case (and the following similar cases) I would either have
the "Conditional" in both names, or neither.

    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.

    @subsubsection Objects @samp{created with both libtool and without}

Why @samp?  Is this more error message text?

    address@hidden Third-party files
    address@hidden Third-party files

Files should be capitalized for consistency.  Probably something to
check throughout ...

    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 :).

    +* 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.

That's an unusual description in the menu, but interesting :).

    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,
Karl




reply via email to

[Prev in Thread] Current Thread [Next in Thread]