Info - some notes about customization

Info - some notes about customization

[Lennart Borgman]

Some time ago a request was made for comments on the documentation. Here are
some comments on Info.

On the Info start page in the part "Important General Concepts" I think
"Command Arguments" is a bit misleading. A little bit up there is a node
called "Commands" and those names are too close in my opinion. I would
suggest renaming the first one to "Command Line Options".

I would also would recommend moving the node "Customization" here too this
part, since this is really an important concept.

"Easy Customization" is quite hard to find now and I believe it would be
much easier to find it if it where put on the node "Customization" than now
when it is under "Variables".

IA link to "Easy Customization" should then also be put under "Examining"
which in the description says "Examining or setting one variable's value".

- Lennart

Re: Info - some notes about customization

[Juri Linkov]

"Lennart Borgman" <lennart.borgman.073@student.lu.se> writes:
> On the Info start page in the part "Important General Concepts" I think
> "Command Arguments" is a bit misleading. A little bit up there is a node
> called "Commands" and those names are too close in my opinion. I would
> suggest renaming the first one to "Command Line Options".

The node "Command Arguments" can't be renamed because then the
standalone Info reader will fail to find this node with its
-O, --show-options, --usage option.

It looks for the following names:

    "%s invocation",
    "Invoking %s",
    "Preliminaries",	/* m4 has Invoking under Preliminaries! */
    "Invocation",
    "Command Arguments",/* Emacs */
    "Invoking `%s'",
    "%s options",
    "Options",
    "Option ",		/* e.g. "Option Summary" */
    "Invoking",
    "All options",	/* tar, paxutils */
    "Arguments",
    "%s cmdline",	/* ar */
    "%s",		/* last resort */

and will find a completely irrelevant node when the
"Command Arguments" node becomes renamed to something else.

Maybe the node name should be changed in the standalone Info reader
as well, but such a change is still not backward compatible.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Info - some notes about customization

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sun, 05 Dec 2004 20:31:24 +0200
> Cc: eliz@gnu.org, emacs-devel@gnu.org, karl@freefriends.org
> 
> The node "Command Arguments" can't be renamed because then the
> standalone Info reader will fail to find this node with its
> -O, --show-options, --usage option.

It could be changed to one of the other node names that --usage looks
for.

> It looks for the following names:
> 
>     "%s invocation",
>     "Invoking %s",
>     "Preliminaries",	/* m4 has Invoking under Preliminaries! */
>     "Invocation",
>     "Command Arguments",/* Emacs */
>     "Invoking `%s'",
>     "%s options",
>     "Options",
>     "Option ",		/* e.g. "Option Summary" */
>     "Invoking",
>     "All options",	/* tar, paxutils */
>     "Arguments",
>     "%s cmdline",	/* ar */
>     "%s",		/* last resort */
> 
> and will find a completely irrelevant node when the
> "Command Arguments" node becomes renamed to something else.

The fact that the Info reader needs to jump through the hoops to find
the node that describes the command-line arguments is IMHO an evidence
of poor adherence to GNU coding standards.  It is IMHO a shame that
Emacs, of all GNU programs, is one of those which required the crazy
code I wrote to implement --usage, since standards.texi explicitly
says that a manual should have a node "PROGRAM Invocation" or
"Invoking PROGRAM", so that "info --usage" could find it.

So perhaps it's high time we changed the Emacs manual to have a node
"Emacs Invocation" ("Invoking Emacs" will interfere with the already
existing "Invoking emacsclient"), which will solve both of the
problems in one blow.

Re: Info - some notes about customization

[Richard Stallman]

    The node "Command Arguments" can't be renamed because then the
    standalone Info reader will fail to find this node with its
    -O, --show-options, --usage option.

I didn't know that.

    It looks for the following names:

	"%s invocation",
	"Invoking %s",
	"Preliminaries",	/* m4 has Invoking under Preliminaries! */
	...

I renamed it to Emacs Invocation, to follow the usual standard.