Add two-parameter versions of @ruser etc. to allow specifying the displayed text

Sometimes node named cannot contain special characters, which you would like
to be displayed in the link text. Thus, the third argument of @ref needs to be
used. Unfortunately, Texinfo (or rather texi2pdf) does not support optional
arguments to macros, so we have to add new two-parameter versions of all our
xref macros.

I als streamlined the definitions in macros.itely a little bit (distinguish only bigpage, not bigpage and tex).

This also allows us to link to the Top node of any manual with displaying the
manual title instead of "Top".

diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely
index 32e425a216fdae1bf573bfd9e761156dacb230a2..198d103a76b3e6e9f9915e786bba535590caa149 100644 (file)
--- a/Documentation/user/introduction.itely
+++ b/Documentation/user/introduction.itely
@@ -870,7 +870,7 @@ all.
 @cindex foreign languages
 @cindex language
 
-@ref{Top,Music glossary,,music-glossary}:
+@rglosnamed{Top,Music glossary}
 this explains musical terms, and includes translations to various
 languages.  If you are not familiar with music notation or music
 terminology (especially if you are a non-native English speaker),
@@ -993,7 +993,7 @@ formats to the @code{.ly} format.
 @cindex snippets
 @cindex LSR
 
-@ref{Top,LilyPond Snippet List,,lilypond-snippets}: this shows a
+@rlsrnamed{Top,LilyPond Snippet List}: this shows a
 selected set of LilyPond snippets from the
 @uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}
 (LSR).  All the snippets are in the public domain.
@@ -1011,7 +1011,7 @@ The list of snippets for each subsection of the Notation Reference
 @node About the Internals Reference (IR)
 @unnumberedsubsec About the Internals Reference (IR)
 
-@ref{Top,Internals Reference,,lilypond-internals}: this is a set
+@rinternalsnamed{Top,Internals Reference}: this is a set
 of heavily cross linked HTML pages which document the nitty-gritty
 details of each and every LilyPond class, object, and function.
 It is produced directly from the formatting definitions in the

diff --git a/Documentation/user/macros.itexi b/Documentation/user/macros.itexi
index fb4e0e779adf1c184103bc0ce9c3fa3c9e418bbb..639cd02fc80c026a4b8162a46473e7a0a49581f8 100644 (file)
--- a/Documentation/user/macros.itexi
+++ b/Documentation/user/macros.itexi
@@ -127,9 +127,13 @@
 @c     @rprogram
 @c     @rsnippets
 @c     @rinternals
+@c  all these also have a @...named version, which allows to specify the
+@c  displayed text for the reference as second argument
 
-@ifhtml
-@c ***** HTML *****
+@c ***** HTML + bigpage is a special case (other manual names), all other
+@c formats are treated similarly
+
+@ifnottex
 
 @ifset bigpage
 
@@ -138,30 +142,59 @@
 @ref{\TEXT\,,,music-glossary-big-page,Music Glossary}
 @end macro
 
+@macro rglosnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,music-glossary-big-page,Music Glossary}
+@end macro
+
 @macro rlearning{TEXT}
 @vindex \TEXT\
 @ref{\TEXT\,,,lilypond-learning-big-page,Learning Manual}
 @end macro
 
+@macro rlearningnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,lilypond-learning-big-page,Learning Manual}
+@end macro
+
 @macro ruser{TEXT}
 @vindex \TEXT\
 @ref{\TEXT\,,,lilypond-big-page,Notation Reference}
 @end macro
 
+@macro rusernamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,lilypond-big-page,Notation Reference}
+@end macro
+
 @macro rprogram{TEXT}
 @vindex \TEXT\
 @ref{\TEXT\,,,lilypond-program-big-page,Application Usage}
 @end macro
 
+@macro rprogramnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,lilypond-program-big-page,Application Usage}
+@end macro
+
 @macro rlsr{TEXT}
 @ref{\TEXT\,,,lilypond-snippets-big-page,Snippets}
 @end macro
 
+@macro rlsrnamed{TEXT,DISPLAY}
+@ref{\TEXT\,,\DISPLAY\,lilypond-snippets-big-page,Snippets}
+@end macro
+
 @macro rinternals{TEXT}
 @vindex \TEXT\
 @ref{\TEXT\,,,lilypond-internals-big-page,Internals Reference}
 @end macro
 
+@macro rinternalsnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,,lilypond-internals-big-page,Internals Reference}
+@end macro
+
 @end ifset
 
 
@@ -172,44 +205,17 @@
 @ref{\TEXT\,,,music-glossary,Music Glossary}
 @end macro
 
-@macro rlearning{TEXT}
+@macro rglosnamed{TEXT,DISPLAY}
 @vindex \TEXT\
-@ref{\TEXT\,,,lilypond-learning,Learning Manual}
+@ref{\TEXT\,,\DISPLAY\,music-glossary,Music Glossary}
 @end macro
 
-@macro ruser{TEXT}
-@vindex \TEXT\
-@ref{\TEXT\,,,lilypond,Notation Reference}
-@end macro
-
-@macro rprogram{TEXT}
-@vindex \TEXT\
-@ref{\TEXT\,,,lilypond-program,Application Usage}
-@end macro
-
-@macro rlsr{TEXT}
-@ref{\TEXT\,,,lilypond-snippets,Snippets}
-@end macro
-
-@macro rinternals{TEXT}
-@vindex \TEXT\
-@ref{\TEXT\,,,lilypond-internals,Internals Reference}
-@end macro
-
-@end ifclear
-
-@end ifhtml
-
-
-@ifdocbook
-@c ***** DOCBOOK-XML *****
-
-@macro rglos{TEXT}
+@macro rlearning{TEXT}
 @vindex \TEXT\
-@ref{\TEXT\,,,music-glossary,Music Glossary}
+@ref{\TEXT\,,,lilypond-learning,Learning Manual}
 @end macro
 
-@macro rlearning{TEXT}
+@macro rlearningnamed{TEXT,DISPLAY}
 @vindex \TEXT\
 @ref{\TEXT\,,,lilypond-learning,Learning Manual}
 @end macro
@@ -219,56 +225,43 @@
 @ref{\TEXT\,,,lilypond,Notation Reference}
 @end macro
 
-@macro rprogram{TEXT}
+@macro rusernamed{TEXT,DISPLAY}
 @vindex \TEXT\
-@ref{\TEXT\,,,lilypond-program,Application Usage}
+@ref{\TEXT\,,\DISPLAY\,lilypond,Notation Reference}
 @end macro
 
-@macro rlsr{TEXT}
-@ref{\TEXT\,,,lilypond-snippets,Snippets}
+@macro rprogram{TEXT}
+@vindex \TEXT\
+@ref{\TEXT\,,,lilypond-program,Application Usage}
 @end macro
 
-@macro rinternals{TEXT}
+@macro rprogramnamed{TEXT,DISPLAY}
 @vindex \TEXT\
-@ref{\TEXT\,,,lilypond-internals,Internals Reference}
+@ref{\TEXT\,,\DISPLAY\,lilypond-program,Application Usage}
 @end macro
 
-@end ifdocbook
-
-
-@ifinfo
-@c **** INFO ****
-
-@macro rglos{TEXT}
-@vindex \TEXT\
-@ref{\TEXT\,,,music-glossary,Music Glossary}
+@macro rlsr{TEXT}
+@ref{\TEXT\,,,lilypond-snippets,Snippets}
 @end macro
 
-@macro rlearning{TEXT}
-@vindex \TEXT\
-@ref{\TEXT\,,,lilypond-learning,Learning Manual}
+@macro rlsrnamed{TEXT,DISPLAY}
+@ref{\TEXT\,,\DISPLAY\,lilypond-snippets,Snippets}
 @end macro
 
-@macro ruser{TEXT}
+@macro rinternals{TEXT}
 @vindex \TEXT\
-@ref{\TEXT\,,,lilypond,Notation Reference}
+@ref{\TEXT\,,,lilypond-internals,Internals Reference}
 @end macro
 
-@macro rprogram{TEXT}
+@macro rinternalsnamed{TEXT,DISPLAY}
 @vindex \TEXT\
-@ref{\TEXT\,,,lilypond-program,Application Usage}
+@ref{\TEXT\,,\DISPLAY\,lilypond-internals,Internals Reference}
 @end macro
 
-@macro rlsr{TEXT}
-@ref{\TEXT\,,,lilypond-snippets,Snippets}
-@end macro
+@end ifclear
 
-@macro rinternals{TEXT}
-@vindex \TEXT\
-@ref{\TEXT\,,,lilypond-internals,Internals Reference}
-@end macro
+@end ifnottex
 
-@end ifinfo
 
 
 @c **** TEX ****
@@ -279,26 +272,52 @@
 @ref{\TEXT\,,,music-glossary,Music Glossary}
 @end macro
 
+@macro rglosnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@ref{\TEXT\,,\DISPLAY\,music-glossary,Music Glossary}
+@end macro
+
 @macro rlearning{TEXT}
 learning manual, @ref{\TEXT\,,,lilypond-learning,Learning Manual}
 @end macro
 
+@macro rlearningnamed{TEXT,DISPLAY}
+learning manual, @ref{\TEXT\,,\DISPLAY\,lilypond-learning,Learning Manual}
+@end macro
+
 @macro ruser{TEXT}
 notation reference, @ref{\TEXT\,,,lilypond,Notation Reference}
 @end macro
 
+@macro rusernamed{TEXT,DISPLAY,DISPLAY}
+notation reference, @ref{\TEXT\,,\DISPLAY\,lilypond,Notation Reference}
+@end macro
+
 @macro rprogram{TEXT}
 program usage manual, @ref{\TEXT\,,,lilypond-program,Application Usage}
 @end macro
 
+@macro rprogramnamed{TEXT,DISPLAY}
+program usage manual, @ref{\TEXT\,,\DISPLAY\,lilypond-program,Application Usage}
+@end macro
+
 @macro rlsr{TEXT}
 @ref{\TEXT\,,,lilypond-snippets,Snippets}
 @end macro
 
+@macro rlsrnamed{TEXT,DISPLAY}
+@ref{\TEXT\,,\DISPLAY\,lilypond-snippets,Snippets}
+@end macro
+
 @macro rinternals{TEXT}
 @vindex \TEXT\
 @code{\TEXT\}
 @end macro
 
+@macro rinternalsnamed{TEXT,DISPLAY}
+@vindex \TEXT\
+@code{\DISPLAY\}
+@end macro
+
 @end iftex