[5401] split @url documentation, describe PDF-only options \urefurlonlylinktrue, \linkcolor, \urlcolor

[karl]

Revision: 5401
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=5401
Author:   karl
Date:     2014-01-06 23:49:17 +0000 (Mon, 06 Jan 2014)
Log Message:
-----------
split @url documentation, describe PDF-only options \urefurlonlylinktrue, 
\linkcolor, \urlcolor

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/NEWS
    trunk/doc/texinfo.texi

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2014-01-01 18:32:23 UTC (rev 5400)
+++ trunk/ChangeLog     2014-01-06 23:49:17 UTC (rev 5401)
@@ -1,3 +1,12 @@
+2014-01-06  Karl Berry  <address@hidden>
+
+       * doc/texinfo.texi (@url): split into several nodes:
+       (@t{@@url} Examples,
+         URL Line Breaking,
+         @t{@@url} PDF Output Format,
+         PDF Colors).  Document the PDF-only \urefurlonlylinktrue
+         and \linkcolor, \urlcolor texinfo.tex features.
+
 2014-01-01  Karl Berry  <address@hidden>
 
        * Pod-Simple-Texinfo/pod2texi.pl,

Modified: trunk/NEWS
===================================================================
--- trunk/NEWS  2014-01-01 18:32:23 UTC (rev 5400)
+++ trunk/NEWS  2014-01-06 23:49:17 UTC (rev 5401)
@@ -26,6 +26,7 @@
 * texinfo.tex:
   . @url/@uref output now the same in PDF as in DVI, showing the url
     even if the second argument is given, not just as link target.
+    Option \urefurlonlylinktrue gives previous behavior of invisible urls.
     
 5.2 (26 September 2013)
 * Language:

Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi      2014-01-01 18:32:23 UTC (rev 5400)
+++ trunk/doc/texinfo.texi      2014-01-06 23:49:17 UTC (rev 5401)
@@ -6896,62 +6896,45 @@
 @cindex URL, referring to
 
 @cindex @code{href}, producing HTML
address@hidden@@uref} produces a reference to a uniform resource locator (url).
-It takes one mandatory argument, the url, and two optional arguments
-which control the text that is displayed.  In HTML output, @code{@@uref}
-produces a link you can follow.
address@hidden@@uref} produces a reference to a uniform resource locator
+(url).  It takes one mandatory argument, the url, and two optional
+arguments which control the text that is displayed.  In HTML and PDF
+output, @code{@@uref} produces a link you can follow.  (To merely
+indicate a url without creating a link people can follow, use
address@hidden@@indicateurl}, @address@hidden@@indicateurl}}.)
 
 @anchor{url} @code{@@url} is a synonym for @code{@@uref}.
-(Originally, @code{@@url} had the meaning of @code{@@indicateurl}
-(@address@hidden@@indicateurl}}), but in practice it was almost always
-misused.  So we've changed the meaning.)
+(Originally, @code{@@url} had the meaning of @code{@@indicateurl}, but
+in practice it was almost always misused.  So we've changed the
+meaning.)
 
 The second argument, if specified, is the text to display (the default
-is the url itself); in Info and DVI output, but not in HTML output, the
-url is output in addition to this text.
+is the url itself); in Info, DVI, and PDF output, but not in HTML
+output, the url is output in addition to this text.
 
 @cindex Man page, reference to
 The third argument, if specified, is the text to display, but in this
 case the url is not output in any format.  This is useful when the
-text is already sufficiently referential, as in a man page.  If the
-third argument is given, the second argument is ignored.
+text is already sufficiently referential, as in a man page.  Also, if
+the third argument is given, the second argument is ignored.
 
address@hidden Line breaking, and urls
address@hidden Breakpoints within urls
address@hidden allows line breaking within urls at only a few characters
-(which are special in urls): @samp{&}, @samp{.}, @samp{#}, @samp{?},
-and @samp{/} (but not between two @samp{/} characters).  A tiny amount of
-stretchable space is also inserted around these characters to help
-with line breaking.  For HTML output, modern browsers will also do
-line breaking within displayed urls.  If you need to allow breaks at
-other characters you can insert @code{@@/} as needed (@pxref{Line
-Breaks}).
address@hidden
+* @t{@@url} Examples::           Examples of using all the forms of 
@code{@@url}.
+* URL Line Breaking::       How lines are broken within @code{@@url} text.
+* @t{@@url} PDF Output Format::  A special option to hide links in PDF output.
+* PDF Colors::              Colorizing urls and other links in PDF output.
address@hidden menu
 
address@hidden urefbreakstyle
-By default, any such breaks at special characters will occur after the
-character.  Some people prefer such breaks to happen after the special
-character.  This can be controlled with the @code{@@urefbreakstyle}
-command (this command has effect only in @TeX{}):
 
-Write this command at the
-beginning of a line with a single word as an argument, one of the
-following:
address@hidden @t{@@url} Examples
address@hidden @t{@@url} Examples
 
address@hidden address@hidden, value for @code{@@urefbreakstyle}}
address@hidden address@hidden, value for @code{@@urefbreakstyle}}
address@hidden address@hidden, value for @code{@@urefbreakstyle}}
address@hidden @samp
address@hidden after
-(the default) Potentially break after the special characters.
address@hidden before
-Potentially break before the special characters.
address@hidden none
-Do not consider breaking at the special characters; any potential
-breaks must be manually inserted.
address@hidden table
address@hidden @t{@@url}, examples of using
address@hidden URL, examples of displaying
 
-Here is an example of the simple one argument form, where the url is
-both the target and the text of the link:
+First, here is an example of the simplest form of @code{@@url}, with
+just one argument.  The given url is both the target and the visible
+text of the link:
 
 @example
 The official GNU ftp site is @@address@hidden://ftp.gnu.org/address@hidden
@@ -6962,38 +6945,40 @@
 The official GNU ftp site is @uref{http://ftp.gnu.org/gnu}.
 @end display
 
address@hidden Two-argument form of @code{@@url}
 
-An example of the two-argument form:
+Here is an example of the two-argument form:
 @example
 The official @@address@hidden://ftp.gnu.org/gnu, GNU ftp address@hidden
 holds programs and texts.
 @end example
 
address@hidden produces:
address@hidden which produces:
 @display
 The official @uref{http://ftp.gnu.org/gnu, GNU ftp site}
 holds programs and texts.
 @end display
 
address@hidden that is, the Info output is this:
address@hidden that is, the Info (and @TeX{}, etc.)@: output is this:
 @example
 The official GNU ftp site (http://ftp.gnu.org/gnu)
 holds programs and texts.
 @end example
 
address@hidden and the HTML output is this:
address@hidden while the HTML output is this:
 @example
 The official <a href="http://ftp.gnu.org/gnu";>GNU ftp site</a>
 holds programs and texts.
 @end example
 
address@hidden Three-argument form of @code{@@url}
 
-An example of the three-argument form:
+Finally, an example of the three-argument form:
 @example
 The @@address@hidden/man.cgi/1/ls,,address@hidden program @dots{}
 @end example
 
address@hidden produces:
address@hidden which, except for HTML, produces:
 @display
 The @uref{/man.cgi/1/ls,,ls} program @dots{}
 @end display
@@ -7003,8 +6988,10 @@
 The <a href="/man.cgi/1/ls">ls</a> program @dots{}
 @end example
 
-Some people prefer to display urls in the unambiguous format:
 
+By the way, some people prefer to display urls in the unambiguous
+format:
+
 @display
 <URL:http://@var{host}/@var{path}>
 @end display
@@ -7013,13 +7000,123 @@
 @cindex @code{<URL...>} convention, not used
 You can use this form in the input file if you wish.  We feel it's not
 necessary to include the @samp{<URL:} and @samp{>} in the output,
-since any software that tries to detect urls in text already has to
-detect them without the @samp{<URL:} to be useful.
+since to be useful any software that tries to detect urls in text
+already has to detect them without the @samp{<URL:}.
 
-To merely indicate a url without creating a link people can follow,
-use @code{@@indicateurl} (@address@hidden@@indicateurl}}).
 
address@hidden URL Line Breaking
address@hidden URL Line Breaking
 
address@hidden Line breaking, and urls
address@hidden Breakpoints within urls
address@hidden allows line breaking within urls at only a few characters
+(which are special in urls): @samp{&}, @samp{.}, @samp{#}, @samp{?},
+and @samp{/} (but not between two @samp{/} characters).  A tiny amount
+of stretchable space is also inserted around these characters to help
+with line breaking.
+
+For HTML output, modern browsers will also do line breaking within
+displayed urls.  If you need to allow breaks at other characters you
+can insert @code{@@/} as needed (@pxref{Line Breaks}).
+
address@hidden urefbreakstyle
+By default, in @TeX{} any such breaks at special characters will occur
+after the character.  Some people prefer such breaks to happen after
+the special character.  This can be controlled with the
address@hidden@@urefbreakstyle} command (this command has effect only in
address@hidden):
+
address@hidden
+@@urefbreakstyle @var{how}
address@hidden example
+
address@hidden where the argument @var{how} is one of these words:
+
address@hidden address@hidden, value for @code{@@urefbreakstyle}}
address@hidden address@hidden, value for @code{@@urefbreakstyle}}
address@hidden address@hidden, value for @code{@@urefbreakstyle}}
address@hidden @samp
address@hidden after
+(the default) Potentially break after the special characters.
address@hidden before
+Potentially break before the special characters.
address@hidden none
+Do not consider breaking at the special characters at all; any potential
+breaks must be manually inserted.
address@hidden table
+
+
address@hidden @t{@@url} PDF Output Format
address@hidden @t{@@url} PDF Output Format
+
address@hidden PDF output of urls
address@hidden URLs, PDF output of
+
+If the ultimate purpose of a PDF is only to be viewed online, perhaps
+similar to HTML in some inchoate way, you may not want the urls to be
+included in the visible text (just as urls are not visible to readers
+of web pages).  Texinfo provides a PDF-specific option for this, which
+must be used inside @code{@@tex}:
+
address@hidden \urefurlonlylinktrue
address@hidden
+@@tex
+\global\urefurlonlylinktrue
+@@end tex
address@hidden example
+
+The result is that @code{@@address@hidden://www.gnu.org, address@hidden has the
+visible output of just `GNU', with a link target of
address@hidden://www.gnu.org}.  Ordinarily, the visible output would
+include both the label and the url: `GNU (@url{http://www.gnu.org})'.
+
+This option only has effect when the PDF output is produced with the
address@hidden program, not with other ways of getting from Texinfo to PDF
+(e.g., @TeX{} to DVI to PDF).  Consequently, it is ok to specify this
+option unconditionally within @code{@@tex}, as shown above.  It is
+ignored when DVI is being produced.
+
+
address@hidden PDF Colors
address@hidden PDF Colors
+
address@hidden Colored links, in PDF output
address@hidden Links, coloring in PDF output
address@hidden URLs, coloring in PDF output
+
+By default, urls and cross-reference links are printed in black in PDF
+output.  Very occasionally, however, you may want to highlight such
+``live'' links with a different color, as is commonly done on web
+pages.  Texinfo provides a PDF-specific option for specifying these
+colors, which must be used inside @code{@@tex}:
+
address@hidden \linkcolor
address@hidden \urlcolor
address@hidden
+@@tex
address@hidden 0 address@hidden  % red
address@hidden 1 address@hidden   % green
+@@end tex
address@hidden example
+
address@hidden changes the color of @code{@@url} output (both the
+actual url and any textual label), while @code{\linkcolor} changes the
+color for cross-references to nodes, etc.  They are independent.
+
address@hidden RGB color specification.
+The three given values must be numbers between 0 and 1, specifying the
+amount of red, green, and blue respectively.
+
+These definitions only have an effect when the PDF output is produced
+with the address@hidden program, not with other ways of getting from
+Texinfo to PDF (e.g., @TeX{} to DVI to PDF).  Consequently, it is ok
+to specify this option unconditionally within @code{@@tex}, as shown
+above.  It is ignored when DVI is being produced.
+
+We do not recommend colorizing just for fun; unless you have a
+specific reason to use colors, best to skip it.
+
+
 @node @t{@@cite}
 @section @code{@@address@hidden@address@hidden