Markdown: allow trailing '[]' to be omitted

When using the "implicit link name" shortcut (i.e. the link name is the same as the link text), the trailing '[]' is unsightly. Allow the trailing '[]' to be omitted when the omission is unambiguous. In other words, if there is no preceding or following pair of square brackets the trailing '[]' can safely be omitted. For example: See any of [link 1][] [link 2][] [lnik 3][]. The trailing '[]' MUST NOT be omitted in this case because the result: See any of [link 1] [link 2] [link 3] would be misinterpreted. But, if they're separated with commas or words instead like so: See any of [link 1], [link 2] or [link 3]. then they cannot be misinterpreted and the trailing '[]' can be safely omitted making for a much nicer looking document. To go with this change the basics.md and syntax.md documents have been modified to take advantage of these new semantics. Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
7 years ago · 18b456b8b4
3 changed files with 115 additions and 33 deletions
--- a/Markdown.pl
+++ b/Markdown.pl
@ -846,7 +846,7 @@ sub _DoAnchors {
    }xsge;

    #
-    # Finally, inline-style links: [link text](url "optional title")
+    # Subsequently, inline-style links: [link text](url "optional title")
    #
    $text =~ s{
 	(		# wrap whole match in $1
@ -888,6 +888,41 @@ sub _DoAnchors {
 	$result;
    }xsge;

+    #
+    # Finally, handle reference-style implicit shortcut links: [link text]
+    #
+    $text =~ s{
+	(		    # wrap whole match in $1
+	  \[
+	    ($g_nested_brackets) # link text = $2
+	  \]
+	)
+    }{
+	my $result;
+	my $whole_match = $1;
+	my $link_text	= $2;
+	my $link_id	= lc $2;
+
+	if (defined($g_urls{$link_id}) || defined($g_anchors{$link_id})) {
+	    my $url = $g_urls{$link_id};
+	    $url = defined($url) ? _PrefixURL($url) : $g_anchors{$link_id};
+	    # We've got to encode these to avoid conflicting
+	    # with italics, bold and strike through.
+	    $url =~ s!([*_~])!$g_escape_table{$1}!g;
+	    $result = "<a href=\"$url\"";
+	    if ( defined $g_titles{$link_id} ) {
+		my $title = $g_titles{$link_id};
+		$title =~ s!([*_~])!$g_escape_table{$1}!g;
+		$result .=  " title=\"$title\"";
+	    }
+	    $result .= ">$link_text</a>";
+	}
+	else {
+	    $result = $whole_match;
+	}
+	$result;
+    }xsge;
+
    return $text;
 }

@ -994,6 +1029,43 @@ sub _DoImages {
 	$result;
    }xsge;

+    #
+    # Finally, handle reference-style implicitly labeled links: ![alt text]
+    #
+    $text =~ s{
+	(		# wrap whole match in $1
+	  !\[
+	    (.*?)	# alt text = $2
+	  \]
+	)
+    }{
+	my $result;
+	my $whole_match = $1;
+	my $alt_text	= $2;
+	my $link_id	= lc $2;
+
+	$alt_text =~ s/"/&quot;/g;
+	if (defined $g_urls{$link_id}) {
+	    my $url = _PrefixURL($g_urls{$link_id});
+	    # We've got to encode these to avoid conflicting
+	    # with italics, bold and strike through.
+	    $url =~ s!([*_~])!$g_escape_table{$1}!g;
+	    $result = "<img src=\"$url\" alt=\"$alt_text\"";
+	    if (defined $g_titles{$link_id}) {
+		my $title = $g_titles{$link_id};
+		$title =~ s!([*_~])!$g_escape_table{$1}!g;
+		$result .=  " title=\"$title\"";
+	    }
+	    $result .= $opt{empty_element_suffix};
+	}
+	else {
+	    # If there's no such link ID, leave intact:
+	    $result = $whole_match;
+	}
+
+	$result;
+    }xsge;
+
    return $text;
 }

--- a/basics.md
+++ b/basics.md
@ -3,8 +3,8 @@ Markdown: Basics
 ================

 * _[Markdown Basics]( "Markdown Basics")_
-* [Syntax][]
-* [License][]
+* [Syntax]
+* [License]

 - - - - -

--- a/syntax.md
+++ b/syntax.md
@ -2,32 +2,32 @@
 Markdown: Syntax
 ================

-* [Markdown Basics][]
+* [Markdown Basics]
 * _[Syntax]( "Markdown Syntax Documentation")_
-* [License][]
+* [License]

 - - - - -

-*   [Overview][]
-    *   [Philosophy][]
-    *   [Inline HTML][]
-    *   [Automatic Escaping for Special Characters][]
-*   [Block Elements][]
-    *   [Paragraphs and Line Breaks][]
-    *   [Headers][]
-    *   [Blockquotes][]
-    *   [Lists][]
-    *   [Style Sheet][]
-    *   [Code Blocks][]
-    *   [Horizontal Rules][]
-*   [Span Elements][]
-    *   [Links][]
-    *   [Emphasis][]
-    *   [Code][]
-    *   [Images][]
-*   [Miscellaneous][]
-    *   [Backslash Escapes][]
-    *   [Automatic Links][]
+*   [Overview]
+    *   [Philosophy]
+    *   [Inline HTML]
+    *   [Automatic Escaping for Special Characters]
+*   [Block Elements]
+    *   [Paragraphs and Line Breaks]
+    *   [Headers]
+    *   [Blockquotes]
+    *   [Lists]
+    *   [Style Sheet]
+    *   [Code Blocks]
+    *   [Horizontal Rules]
+*   [Span Elements]
+    *   [Links]
+    *   [Emphasis]
+    *   [Code]
+    *   [Images]
+*   [Miscellaneous]
+    *   [Backslash Escapes]
+    *   [Automatic Links]


 **Note:** This document is itself written using Markdown; you
@ -408,14 +408,14 @@ list number ahead which again should be effective in just about any
 browser available today.

 A right parenthesis ')' may be used in place of the `.` for any of the
-numbering styles but it requires the [style sheet][] to be included or
+numbering styles but it requires the [style sheet] to be included or
 you will end up just seeing `.` instead.  For example this list:

      a)  Alpha
      b)  Beta
      c)  Gamma

-will end up being displayed like this without the [style sheet][]:
+will end up being displayed like this without the [style sheet]:

      a.  Alpha
      b.  Beta
@ -440,7 +440,7 @@ list marker.

 To create two distinct lists when there are only blank lines between the
 end of the first list and the start of the second, a separator line must
-be inserted.  ([Horizontal rules][] work just fine for this).
+be inserted.  ([Horizontal rules] work just fine for this).

 If desired, an HTML-style comment (e.g. `<!-- -->`) may be used for this
 purpose provided it is preceded and followed by at least one blank line.
@ -775,11 +775,15 @@ are equivalent.

 The *implicit link name* shortcut allows you to omit the name of the
 link, in which case the link text itself is used as the name.
-Just use an empty set of square brackets -- e.g., to link the word
-"Google" to the google.com web site, you could simply write:
+Just use an empty set of square brackets (or none) -- e.g., to link the
+word "Google" to the google.com web site, you could simply write:

      [Google][]

+Or even just this:
+
+      [Google]
+
 And then define the link:

      [Google]: http://google.com/
@ -787,12 +791,18 @@ And then define the link:
 Because link names may contain spaces, this shortcut even works for
 multiple words in the link text:

-      Visit [Daring Fireball][] for more information.
+      Visit [Daring Fireball] for more information.

 And then define the link:

      [Daring Fireball]: http://daringfireball.net/

+Text inside square brackets is left completely unchanged (including the
+surrounding brackets) _unless_ it matches a link definition.  Furthermore,
+the single pair of surrounding square brackets case is always checked
+for last so you may only omit the trailing `[]` of an *implicit link name*
+shortcut when the result would still be unambiguous.
+
 Link definitions can be placed anywhere in your Markdown document. I
 tend to put them immediately after each paragraph in which they're
 used, but if you want, you can put them all at the end of your
@ -817,8 +827,8 @@ Here's an example of reference links in action:

 Using the implicit link name shortcut, you could instead write:

-      I get 10 times more traffic from [Google][] than from
-      [Yahoo][] or [MSN][].
+      I get 10 times more traffic from [Google] than from
+      [Yahoo] or [MSN].

      [google]: http://google.com/        "Google"
      [yahoo]:  http://search.yahoo.com/  "Yahoo Search"