[Top][All Lists]
[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