From 2dd1ed27043726b02ed8a8d766da7b0aa61539a9 Mon Sep 17 00:00:00 2001
From: Pascal Hertleif <killercup@gmail.com>
Date: Tue, 7 Mar 2017 15:27:47 +0100
Subject: [PATCH] Update intra_rustdoc_links

- Mention this is valid Markdown
- Add more alternatives
---
 text/0000-intra-rustdoc-links.md | 41 ++++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/text/0000-intra-rustdoc-links.md b/text/0000-intra-rustdoc-links.md
index 2a95a6c8a69..c1bbf3757f8 100644
--- a/text/0000-intra-rustdoc-links.md
+++ b/text/0000-intra-rustdoc-links.md
@@ -80,6 +80,16 @@ it should also be possible to write a Rust path
   and somewhere else in the document: `[iter]: std::iter::Iterator`
 3. `<std::iter::Iterator>`
 
+All additions are already valid Markdown,
+as defined by the orginal [Markdown syntax definition][md]
+as well as the [CommonMark] project.
+Especially, Rust paths are valid CommonMark [link destinations],
+even with the suffixes described [below][path-ambiguities].
+
+[md]: https://daringfireball.net/projects/markdown/syntax
+[CommonMark]: http://commonmark.org
+[link destinations]: http://spec.commonmark.org/0.27/#link-destination
+
 ## How it will be rendered
 
 The following:
@@ -146,6 +156,7 @@ mod amet {
 ```
 
 ## Path ambiguities
+[path-ambiguities]: #path-ambiguities
 
 Rust allows items to have the same name. A short evaluation revealed that
 
@@ -173,7 +184,9 @@ This was originally proposed by
 going into more details:
 
 > `<syntax::ptr::P>` — First search for type-like items. If not found, search for value-like items
+>
 > `<syntax::ptr::P()>` — Only search for functions.
+>
 > `<std::stringify!>` — Only search for macros.
 
 ## Linking to methods
@@ -271,9 +284,29 @@ Maybe present an example use case of a module whose documentation links to sever
 # Alternatives
 [alternatives]: #alternatives
 
-## Syntax alternatives
+- Use reference-style links and automatically generate the references.
+  For example, the Markdown snippet
+
+  ```md
+  This is of type [`String`].
+  ```
+
+  expects a link reference definition like
 
-Introduce special syntax for this:
+  ```md
+  [`String`]: https://doc.rust-lang.org/nightly/std/string/struct.String.html
+  ```
+
+  to follow (or precede) it.
+  This link reference definition can be automatially generated by Rustdoc
+  with the (relative) URL to the page of the item.
+  This was suggested in [the CommonMark forum]
+  as well as
+  by [GuillaumeGomez](https://github.com/GuillaumeGomez).
+
+  We consider this equivalent to the `<String>` syntax this RFC proposes.
+
+[cm-forum]: https://talk.commonmark.org/t/what-should-the-rust-community-do-for-linkage/2141
 
 - [javadoc] and [jsdoc]
   use `{@link java.awt.Panel}`
@@ -282,6 +315,10 @@ Introduce special syntax for this:
 [javadoc]: http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html
 [jsdoc]: http://usejsdoc.org/tags-inline-link.html
 
+- [@kennytm](https://github.com/kennytm)
+  listed other syntax alternatives
+  [here](https://github.com/rust-lang/rfcs/pull/1946#issuecomment-284718018).
+
 
 # Unresolved questions
 [unresolved]: #unresolved-questions