Fix broken WEB links

[wilzbach]

As mentioned in dlang/dlang.org#1337 and dlang/dlang.org#1333, yet another sed adventure!
Today's purge are the WEB, HTTP, HTTPS macros.

Reason: We still have way too many custom ddoc macros to make simple links - creating a link should be simple!
Have a look at this selection:

A = <a href="$1">$+</a>
AHTTP = <a href="http://$1">$+</a>
AHTTPS = <a class="https" href="https://$1">$+</a>
ALOCAL = <a href="#$1">$+</a>

LINK = $(A $0, $0)
LINK2 = $(A $1, $+)

HTTP = $(LINK2 http://$1,$2)
HTTPS = $(LINK2 https://$1,$2)
WEB = $(HTTP $1,$2)

Some people might argue that WEB is great, because it's a bit shorter, but

• it leads to problems if you think it's a normal link and use http:// (happens quite often, even here in Phobos)
• it discourages the fact that we are in 2016 and SSL should be everywhere. WEB always resolves to http://
• yet another macro that does the same thing

Or to quote Andrei from a recent forum discussion:

Yah, I wouldn't disagree things can be vastly improved. My point there is to make sure we distinguish > what's trivially fixable (e.g. redundant macro definitions) from larger issues. Again, if you find identical macros across dd/ddoc files, or redundant macros that do the same thing in just slightly different ways, please fix or file. Thanks!

Andrei
http://forum.dlang.org/post/ni4b13$21go$1@digitalmars.com

Hence this PR replaces all WEB, HTTP and HTTPS macros with LINK2. Ideally in the future we can use "markdown-like" links in ddoc - we all love them from Github, right?

Commands

This PR is done fully automated - again regular expressions to the help!

1. fix broken WEB links sed 's/(WEB http:\/\//(WEB /' -i **/*.d
2. HTTP links sed 's/(WEB /(LINK2 http:\/\//' -i */.d
3. single-line WEB links sed 's/\$(WEB$/\$(LINK2\nhttp:\/\//' -i **/*.d
4. multi-line links perl -0777 -i -pe 's/\$\(WEB\n(\s*)/\$(LINK2\n\1http:\/\//g' **/*.d

Should I add a simple grep to travis.yml or can we ensure - with the help of DAutotester - that those macros aren't used in the future?

[dnadlinger]

Are these used/useful for the LaTeX output?

[wilzbach]

Are these used/useful for LaTeX?

LaTeX only overwrites the A macro to which they all boil down eventually.

A=\ref{$1}{$+}

edit: LINK2 stops the macro expansion earlier (but they still all boil down to LINK2)

LINK2=\hyperlink{$1}{$+}

[wilzbach]

Btw as this mostly changes the license header urls (other links already use LINK2) - shouldn't we link to our own copy at https://github.com/dlang/phobos/blob/master/LICENSE_1_0.txt?

[veelo]

Resolve the merge conflict by incorporating #4409: $(MREF_ALTTEXT region allocation strategy, std,experimental,allocator,building_blocks,region).

[wilzbach]

Resolve the merge conflict

Done ;-)

[aG0aep6G]

Unfortunately, this is no good. Ddoc interprets "http:" as a section. Can't have a break between "LINK2" and "http:".

[wilzbach]

Unfortunately, this is no good. Ddoc interprets "http:" as a section. Can't have a break between "LINK2" and "http:".

Okay I adapted the regular expression for the last commit to put the $(LINK2 into the next line too (remembering the whitespace of course).

perl -0777 -i -pe 's/ \$\(WEB\n(\s*)/\n\1\$(LINK2 http:\/\//g' **/*.d

[aG0aep6G]

Looks good to me.

[wilzbach]

(somehow I pressed on the wrong button - sorry)

[andralex]

Macros that encapsulate the protocol are actually useful and should stay. If anything LINK2 might be phased out. The problem goes as follows. Links are usually long strings with no space in between. So whenever they occur in text, editors see them as a long word. Some editors have a "format paragraph" feature that breaks long lines into multiple lines. Naturally, since the link is a long word, it often appears as the only (or first) word on a line. At that point, something very unpleasant happens: DDOC thinks "http:" is a paragraph heading (like "Returns:" and the rest of the URL is the rest of the paragraph. So the format gets messed up. The fix is awkward - you need to always make sure something else comes before the URL on each line. Obviously editors have no idea about that.

So using $(HTTP this.is/a/very/long/url, text) instead of $(LINK2 http:/this.is/a/very/long/url, text) has two benefits. First, it fixes the problem above with ddoc and :. Second, it makes the URL itself shorter (= easier to format in the paragraph) and easier to type.

(I don't understand the argument around WEB. Aren't modern sites switching automatically to HTTPS if asked for HTTP?)

Anyhow, I suggest consolidating around HTTP and HTTPS (and FTP if necessary) and phasing out everything else. Works?

[wilzbach]

(I don't understand the argument around WEB. Aren't modern sites switching automatically to HTTPS if asked for HTTP?)

Yes, but only a small minority (only 21 from the Top 100 enable SSL by default) :/

https://www.wired.com/2016/03/https-adoption-google-report/

Anyhow, I suggest consolidating around HTTP and HTTPS (and FTP if necessary) and phasing out everything else. Works?

Alrighty - I rebased the PR to just include the fix for the broken WEB links.

[andralex]

Thanks, so far so good. Feel free to replace WEB with HTTP/HTTPS in a later pass.

[aG0aep6G]

Naturally, since the link is a long word, it often appears as the only (or first) word on a line. At that point, something very unpleasant happens: DDOC thinks "http:" is a paragraph heading
[...]
So using $(HTTP this.is/a/very/long/url, text) instead of $(LINK2 http:/this.is/a/very/long/url, text) has two benefits. First, it fixes the problem above with ddoc and :.

But then you run straight into the next issue. The supposed fix doesn't work with indentation:

    $(HTTP
    this.is/a/very/long/url, text)

This puts spaces between "http://" and "this.is/a/very/long/url", breaking the URL. Generally, having anything but a single space between the macro name and the first argument is asking for trouble.

So all HTTP buys us is this:

Second, it makes the URL itself shorter (= easier to format in the paragraph) and easier to type.

And the price is:

• Can't just copy/paste a URL from the browser. Need to remove that "http://". People tend to forget to do this, and we get broken links.
• More macros that need to be maintained.

I don't think HTTP is a net benefit.