Re: [help-texinfo] Help with @ref

['Patrice Dumas']

On Fri, Jul 17, 2015 at 03:33:08PM -0700, Arthur Schwarz wrote:
> @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.

Indeed, it should.

> The issue remains that:
> 1: Descriptions of manual conventions are undefined.
> 2: Syntax of, e.g., arguments are undefined.
> 3: tag arguments are undefined.

It is explained at the very beginning of the "Appendix A @-Command
List".  Also at that point, there is a link to "Command Syntax" which
explains the @-commands syntax in general.

> In this case for the @ref tag none of NODE, ENTRY, NOD-TITLE, INFOR-FILE, or
> MANUAL are undefined, nor is the meaning of [...]. 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.

I can't see the "it should be clear" statement in the manual.  I also
fail to see how the fact that you are not a student is relevant.  This
manual is done for anybody interested in Texinfo.  It is meant to be
descriptive and well organized for anybody.

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

The @node is explained in detail in its own section:
http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Nodes

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

The manual has, depending on the format, a main menu/detailed menu or a
short table of contents/table of content, with the "Nodes" section not
that hard to find as well as an index, with "node" pointing to the
section with all the explanations.

> 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. This manual has failed.

We always welcome feedback on the manual, but this feedback is not very
helpful.  The manual indeed descrives the Texinfo format and processors,
I could point you to the different sections, but they are easily
accessible from the table of content/menu.

-- 
Pat