Re: [help-texinfo] Help with @ref

[Arthur Schwarz]

@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.
2: Syntax of, e.g., arguments are undefined.
3: tag arguments are undefined.

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.

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. 

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.

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.

Thank you for your help. Thank you for spending time and effort in trying to
clarify the mysteries.

art

-----Original Message-----
From: Patrice Dumas [mailto:address@hidden 
Sent: Friday, July 17, 2015 3:06 PM
To: Arthur Schwarz
Cc: address@hidden
Subject: Re: [help-texinfo] Help with @ref

On Fri, Jul 17, 2015 at 09:53:28AM -0700, Arthur Schwarz wrote:
> I am attempting to turn an Open Office document into a texinfo document. I
> have done:
> 
>     odt -> HTML -> texi using pandoc
> 
> and have discovered, well, that pandoc doesn't quite work. The major issue
I
> have now is that pandoc has generated, man statements like "1.0 Overview
> @ref{#__RefHeading__4496_490911158,8}". Makeinfo reports an error message
> (@ref reference to nonexistent node `#__RefHeading__4496_490911158') for
> each @ref statement. I think I understand what is meant but the Texinfo
> Manual in Appendix A shows "@ref{ node, [entry], [node-title],
[info-file],
> [manual]}" without any explanation. If would help me if some explanation
is
> available to direct me on fixing the pandoc generated code. 

This part of the manual is terse for good reason, it is a list of every
command.  But there is some text though (in info):

'@ref{NODE, [ENTRY], [NODE-TITLE], [INFO-FILE], [MANUAL]}'
     Make a plain reference that does not start with any special text.
     Follow command with a punctuation mark.  Only the first argument is
     mandatory.  *Note @ref::.

And a reference to the specific @ref explanation in the manual.  There
should be such a reference in any output format which should lead you to
the section you are looking for.


For your particular issue, a @ref{} with only the node name (or @anchor) 
as argument looks good to me, but the document should contain such a
node or anchor, I guess the pandoc generated Texinfo document lacks the
node.

-- 
Pat