Re: @uref doc policy

[Graham Percival]

On Wed, Apr 14, 2010 at 11:46:22PM -0700, Mark Polesky wrote:
> 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).

I wouldn't go that far -- if a link isn't very important, let's
not include it.  For example, in the description of lilypondtool,
the lilypond url should be given explicitly, but the incidental
link to jedit doesn't need to be given explicitly.  The important
thing in that description is lilypondtool.

I'd argue that all the links in Productions are in the same
category.  The main point of that page is to show that people *do*
use lilypond for serious work; the exact links don't need to be
available to everybody.

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

Reasons
- 50%: this forces a newline, otherwise URLs can easily run off
  the right-hand edge of the page.
- 20%: it makes the links easier to copy&paste (just select the
  entire line, instead of hunting around for the
  character-specific boundaries -- this is a serious issue for
  people on netbooks)
- 20%: it avoids the problem of punctuation when including URLs in
  a sentence.  For example, see http://www.google.com/index.html.
  Or what if the end of a clause
  has a http://www.link.example.net/, but the sentence continues?
  The grammar can be confusing, and it makes the copy&paste more
  difficult.
- 10%: explicit links in text looks ugly.  (subjective judgement)

> I'm okay with instituting #1 as a policy, though it will
> require re-structuring a lot of sentences*.

I'm not saying that this should be a blind policy; in each case,
the doc writer should think about whether people really need to
see the url or not.  If yes, @example.  If no, then link text.

> 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

- I'm fine with the url in the ultra-short summary (although it
  should be @uref), since frankly it's just there to show off.
- I suggest rewriting the first paragraph to:
---------- >8
The @q{official} LilyPond Git repository is hosted by the GNU
Savannah software forge at:

@example
@uref{http://git.sv.gnu.org}
@end example

However, since Git uses a @emph{distributed} model, technically
there is no central repository.  Instead, each contributor keeps a
complete copy of the entire repository (about 116M).
---------- >8

- Frankly, I would omit the new second paragraph -- new
  contributors don't need to know distributed stuff.  And since
  lily-git (and the basic git instructions) explicitly *don't* get
  the entire repo (they only get the master branch, and lily-git
  actually only gets the past 10 commits!), the second sentence is
  either misleading or is not correct.

- I would change the next pair of urls to:
---------- >8
The cgit and gitweb interfaces are:

@example
@uref{http://git.sv.gnu.org/cgit/lilypond.git/}
@uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git}
@end example
---------- >8

- I suggest the final pagraph should be:

---------- >8
Contributors can contact the developers through the
@q{lilypond-devel} mailing list.  If you have a question for the
developers, search the archives first to see if the issue has
already been discussed.  Otherwise, send an email to
@email{lilypond-devel@@gnu.org}.  To subscribe or read the
archives, see:

@example
@uref{http://lists.gnu.org/mailman/listinfo/lilypond-devel}.
@end example
---------- >8



>   CG 2.4.8 Commit access, items 1 and 2.

---------- >8
@item
If you don't already have one, set up a Savannah user account at:

@example
@uref{https://savannah.gnu.org/account/register.php}
@end example

If your web browser responds with an @qq{untrusted connection}
message when you visit the link, follow the steps for including
the CAcert root certificate in your browser, given at:

@example
@uref{http://savannah.gnu.org/tls/tutorial/}.
@end example
---------- >8

---------- >8
@item
After registering, if you are not logged in automatically,
login to:

@example
@uref{https://savannah.gnu.org/account/login.php}
@end example

This should take you to your @qq{my} page:

@example
@uref{https://savannah.gnu.org/my/}
@end example
---------- >8


> 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.

I'm not suggesting that it should be done for *all* the urefs;
maybe 80% of them?  rough guess.  Basically, wherever it can be
done without being silly?

> 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?

Ooo, I hadn't thought of that.  In the list of reasons, let's bump
the 50% down to 40%, bump the punctuation-problem to 15%, and add
this one as 15%.

Cheers,
- Graham