sandbox/manpage-writer/URUE-problem.txt

   1 ================
   2  UR UE problems
   3 ================
   4
   5 :Date: $Date$
   6
   7 Testing on ubuntu-23.10 running groff 1.23.0
   8
   9 man 7 man
  10 =========
  11
  12 tells on   *Hypertext link macros*
  13
  14        .UR url
  15               Insert a hypertext link to the URI (URL) url, with all  text  up  to  the
  16               following .UE macro as the link text.
  17
  18        .UE    [trailer]  Terminate  the  link text of the preceding .UR macro, with the
  19               optional trailer (if present, usually a closing parenthesis  and/or
  20               end‐of‐sentence  punctuation) immediately following.  For non‐HTML output
  21               devices (e.g., man -Tutf8), the link text is followed by the URL in angle
  22               brackets;  if  there  is no link text, the URL is printed as its own link
  23               text, surrounded by angle brackets.  (Angle brackets may not be available
  24               on all output devices.)  For the HTML output device, the link text is
  25               hyperlinked to the URL; if there is no link text, the URL is printed as
  26               its own link text.
  27
  28 man 1 man states ::
  29
  30        -t, --troff
  31               Use  groff  -mandoc  to format the manual page to stdout.  This option is
  32               not required in conjunction with -H, -T, or -Z.
  33
  34        -T[device], --troff-device[=device]
  35               This option is used to change groff (or possibly troff’s)  output  to  be
  36               suitable  for  a device other than the default.  It implies -t.  Examples
  37               (provided with Groff‐1.17) include dvi, latin1, ps, utf8, X75 and X100.
  38
  39
  40
  41 examples
  42 ========
  43
  44 URUE.man ::
  45
  46   go to the
  47   .UR http://www.python.org
  48   python home page
  49   .UE
  50   to read
  51
  52   or read
  53   .UR http://www.python.org
  54   .UE
  55
  56 man
  57 ---
  58
  59 ``man ./URUE.man`` renders::
  60
  61   go to the python home page to read
  62
  63   or read
  64
  65 Specifying the device with ``man -Thtml ./URUE.man``
  66 html, utf8 and ps also do not contain an url.
  67
  68 mandoc
  69 ------
  70
  71 txt and html work, ps looses the second url if it is the last thing in the file.
  72
  73 ``mandoc ./URUE.man`` renders::
  74
  75   ()                                                                        ()
  76
  77   go to the python home page <http://www.python.org> to read
  78
  79   or read <http://www.python.org>
  80
  81                                                                             ()
  82 ``mandoc -Tps ./URUE.man | ps2txt`` produces::
  83
  84   ()                                         ()
  85   go to the python home page <http://www.python.org> to read
  86                                              ()
  87
  88 nroff
  89 -----
  90
  91 ``nroff -man ./URUE.man`` to the console produces::
  92
  93   go to the python home page to read
  94
  95   or read http://www.python.org
  96
  97 ``nroff -man ./URUE.man > URUE.nroff`` gives::
  98
  99
 100   go to the \e]8;;http://www.python.org\e\python home page\e]8;;\e\ to read
 101
 102   or read \e]8;;http://www.python.org\e\http://www.python.org\e]8;;\e\
 103
 104
 105 in fact it is OSC8 (Operating System Command 8 ) terminal hyperlinks via
 106 escape sequences. Should work like html ``<a href="url">text</a>``, but does not.
 107 It is more like the string following the first escape sequence is overwritten
 108 by the second ... like making text *bold* on a typewriter.
 109