GNU bug report logs - #7766
docs: work on index issues

Previous Next

Full log

View this message in rfc822 format

From: karl <at> freefriends.org (Karl Berry)
To: Ralf.Wildenhues <at> gmx.de
Cc: 7766 <at> debbugs.gnu.org, automake-patches <at> gnu.org
Subject: bug#7766: (lack of) config.h description in manual
Date: Sun, 9 Jan 2011 00:17:36 GMT

    Hmm, I see a natural split into two, not three nodes.  

Ok, fine.

    Below, I replaced the existing one rather than using another lower
    hierarchy level.  Does this seem acceptable to you?

Sure, but I suggest making the @node names closer to the @section names,
and not using that unusual-looking /.

@node amhello/configure.ac
->
@node amhello's configure.ac Setup Explained

@subsection Configure setup explained
->
@subsection @code{amhello}'s @file{configure.ac} Setup Explained

Ditto for the other node.

And then I think the upper-level menu could just use the node names.

(In general, despite longstanding precedent in various GNU manuals, my
belief is that it is not helpful to readers to have @node names that
unnecessarily differ from their section names.  The result is confusion
when an xref is made.)

Re capitalization, I seem to recall that we tried to systematically
Capitalize Node/Section Names a while back.  I don't see other downcased
names in the top-level menu just now, anyway.

    +@anchor{amhello Explained}

Very good.  Extra credit for thinking to do that :).

Thanks,
k

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.