> From: "Arthur Schwarz" <[email protected]> > Date: Fri, 17 Jul 2015 15:33:08 -0700 > Cc: [email protected] > > @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.
