add URL recognition to Ddoc spec

[WalterBright]

Document enhancement dlang/dmd#7043

[dlang-bot]

Thanks for your pull request, @WalterBright!

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

[wilzbach]

Thanks!

[PetarKirov]

FYI @s-ludwig

[s-ludwig]

@WalterBright: In dlang/dmd#7043 you stated that code like $(LINK http://www.foo.com) won't be affected, but the spec just says that URL recognition happens before macro substitution. I'm missing a link between the two. Is there some intermediate state, where the text is separated into macro and non-macro parts and only the latter are searched for URLs? Also:

• $(LI This is a http://example.com test) - is the URL recognized there?
• $(LI URL: http://example.com) - is the trailing ) part of the URL?

[WalterBright]

@s-ludwig The recognition happens on the raw text. Macro invocations are part of that.

$(LI This is a http://example.com test) - is the URL recognized there?

Yes. It must, as the entire Ddoc text is often in a macro.
https://github.com/dlang/dmd/blob/master/src/ddmd/doc.d#L2429

$(LI URL: http://example.com) - is the trailing ) part of the URL?

No. https://github.com/dlang/dmd/blob/master/src/ddmd/doc.d#L1935

[wilzbach]

Rebased and set to auto-merge as this is now the behavior of DMD.

[PetarKirov]

There's a problem somewhere around the —, because of which the Latex build fails the following rather cryptic error:

! Misplaced alignment tab character &.
l.24904 ...t is emphasized depends on what it is &
                                                  mdash; a function paramete...

? 
! Emergency stop.

[wilzbach]

Not sure about the best preference here, the easiest way to fix -_?=%&/+#~. is to put in a code block, otherwise sth. like '-_?=%$(AMP)/+#~.' would also work

[PetarKirov]

Code blocks look much cleaner.

[PetarKirov]

It looks like now the build is failing because it can't reach code.dlang.org. @wilzbach can you rebase again to restart the build?

[MetaLang]

This looks very weird in the resulting page. I think it'd be better to spell it out and write ...and contain at least one period.

[quickfur]

ping @WalterBright Any updates w.r.t. @MetaLang 's request for changes? Let's get this moving along.

[WalterBright]

Did @MetaLang 's request

[quickfur]

Just an afterthought: is there a way to suppress this URL recognition behaviour? Just an example off the top of my head, that perhaps we're documenting a URL parsing library, and the ddoc would like to give examples of URLs or URL snippets. It would be nice if there was a way to distinguish between these example URLs (that we don't want to generate a link for) vs. real URLs that we do want to generate a link for.

[quickfur]

P.S. In general, I'm wary when something is automated with no way to turn it off. I'm all for smart recognition of URLs, section headings, etc., but there needs to be a way to suppress this behaviour when the automatic behaviour is not desirable. I don't want to see this become yet another train wreck like the auto highlighting of keywords in plain text, that has led to underscore proliferation everywhere in the Phobos docs (and tons of wasted time churning through PRs that do nothing except prefix underscores to words that got highlighted when they shouldn't be).

[MetaLang]

That's a good point, but I think it's something that can easily be added in a follow-up PR.

[andralex]

Here you need to add that the sequences are preceded by whitespace, otherwise asdhttp:// will be considered a URL.

[andralex]

Ironically, github considers the above a URL!

[andralex]

so I guess I'll approve...

[andralex]

Ah, one more thing - the macro should be different from LINK so people can detect and neutralize it if needed. For example it should be DDOC_LINK_AUTODETECT

[quickfur]

Yes, please make it DDOC_LINK_AUTODETECT. This would provide the escape hatch I was alluding to.

[quickfur]

Here: #2127