Re: [help-texinfo] Help with @ref

[Eli Zaretskii]

> From: "Arthur Schwarz" <address@hidden>
> Date: Fri, 17 Jul 2015 15:33:08 -0700
> Cc: address@hidden
> 
> @ref{NODE, [ENTRY], [NODE-TITLE], [INFO-FILE], [MANUAL]}'
> 
> Thank you for trying to help. The nearest I can figure is that the > info
> texinfo reference contains identical information as the pdf/html documents.
> The issue remains that:
> 1: Descriptions of manual conventions are undefined.

They are available in the following nodes of the Texinfo manual:

  Texinfo Document Structure
  Conventions
  Minimum
  Six Parts

and an example is available in "Short Sample".  In general, I
recommend to read the entire chapter "Overview of Texinfo" (node name
"Overview"), if you are a first-time user of Texinfo and need to learn
the basics.

> 2: Syntax of, e.g., arguments are undefined.

The syntax of arguments of of @ref are described under @xref, to which
@ref's description refers.  If you want to read about the characters
allowed within a node name, you will find that in "Node Names" and
"Node Line Requirements".  Again, for first-time usage, reading the
whole "Nodes" chapter is recommended.

> 3: tag arguments are undefined.
> 
> In this case for the @ref tag none of NODE, ENTRY, NOD-TITLE, INFOR-FILE, or
> MANUAL are undefined

See above for the pointers to descriptions of those.

In general, I think you are making a mistake using the appendix as a
self-contained source of information you need.  That appendix is just
an alphabetical list of Texinfo commands, and is not intended for
first-time users.

If you need to use the manual as a reference, i.e. for searching just
the topics you are interested in (as opposed to using it as a book
whose chapters are read more or less in their entirety), you should
look up the topic you are after in the indices, and then read the
nodes to which the index entries point.  For example, "i ref RET", if
typed in an Info reader, will land you in the node that describes the
@ref command; "i node name RET" will land you in the node describing
the syntax and requirements of a node name; etc.  (Here "RET" means
press the "Enter" key on your keyboard.)  Alternatively, simply search
the 2 index nodes, "Command and Variable Index" and "General Index",
for the topic you need to read about, and then follow the hyperlink to
the relevant nodes.  (The 'i' command in an Info reader does that
automatically for you, and it also provides completion if you press
the TAB key.)

> nor is the meaning of [...].

"[..]" means an optional argument, as explained at the very beginning
of the appendix:

  Square brackets, [ ], indicate optional arguments; an ellipsis, '...',
  indicates repeated text.

> The statement that 'it should be clear ...'. has as much meaning as
> 'it is left as an exercise to the student ...', to wit, I am not a
> student and the manual should be descriptive to avoid the reader
> searching through the book for relevant descriptive material.

See above: the manual tries not to assume that things are "clear".  It
describes them explicitly.  However, you need to read more than just
that appendix to find those descriptions.  In fact, even starting from
the appendix is not recommended; it is better to start from the master
menu, as suggested by Patrice, and/or use the index-searching command
(the 'i' command that I show above).

> In this case, what is the syntax of node, e.g., are blanks or special
> characters allowed. What does node represent, e.g., is it a @node, @anchor,
> @anything. 

It's all described in the manual.  I already mentioned some of those
places; for @anchor, type "i anchor RET", and read the node "@anchor"
where that lands you.

> In lieu of having the information at hand I actually guessed at what 'node'
> meant. To my surprise, I guessed correctly, and I found that spaces where
> allowed without the requirement for text brackets. I have no idea of how I
> could have extracted this information from the manual.

I hope I succeeded in explaining above how you could have done that.
In a nutshell, you need to use an Info reader or a Web browser to find
the information via the indices.

> What is the purpose of a manual? My own feeling is that its purpose is to
> provide a description of the thing at hand, and that it succeeds or fails on
> this basis.

That is correct.

> This manual has failed.

I disagree.  I think you've come to this conclusion because you read
the wrong portions of the manual, which is not intended to serve the
purpose you thought it was, and in particular didn't use the indices
to find the information you were after.