Re: @uref doc policy

[Mark Polesky]

Graham Percival wrote:
> How about "if it is important to let people follow the
> link, put it inside an @example" ?  The idea is to make
> sure that people who print the PDFs can see stuff.  If
> it's not too much bother.

It seems to me that there are two unrelated issues that
you've squeezed into one:

1) @uref should only be used with the one-argument form,
   since the 2- and 3- argument forms suppress the printing
   of URLs in the PDF output (which I agree is bad).

2) Putting a @uref inside an @example looks better to Graham
   in certain situations for some reason.

I'm okay with instituting #1 as a policy, though it will
require re-structuring a lot of sentences*.  But I think
you'll have a harder time making a case for #2, since there
are plenty of cases where adding @example blocks will be
disruptive.  Such as:
  CG 1.2 Overview of work flow
  CG 2.4.8 Commit access, items 1 and 2.

*Perhaps we could write a macro that displays @urefs in PDF
the same way they're dislplayed in info?

In fact, all of your arguments support statement 1, and none
of the examples you cited had anything to do with statement
2.  There's a @uref within an @example in the lily-git
documentation (CG 2.1), which I suppose is what you had in
mind, but I just don't see how this will work for the
majority of @urefs in the docs.

Is it that you'd like certain important URLs to "stick out"
so that they're easy to find for people who aren't actually
reading the text?

- Mark