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>

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;
 }
 

basics.md

@@ -3,8 +3,8 @@ Markdown: Basics
 ================
 
 * _[Markdown Basics]( "Markdown Basics")_
-* [Syntax][]
+* [Syntax]
-* [License][]
+* [License]
 
 - - - - -
 

syntax.md

@@ -2,32 +2,32 @@
 Markdown: Syntax
 ================
 
-* [Markdown Basics][]
+* [Markdown Basics]
 * _[Syntax]( "Markdown Syntax Documentation")_
-* [License][]
+* [License]
 
 - - - - -
 
-*   [Overview][]
+*   [Overview]
-    *   [Philosophy][]
+    *   [Philosophy]
-    *   [Inline HTML][]
+    *   [Inline HTML]
-    *   [Automatic Escaping for Special Characters][]
+    *   [Automatic Escaping for Special Characters]
-*   [Block Elements][]
+*   [Block Elements]
-    *   [Paragraphs and Line Breaks][]
+    *   [Paragraphs and Line Breaks]
-    *   [Headers][]
+    *   [Headers]
-    *   [Blockquotes][]
+    *   [Blockquotes]
-    *   [Lists][]
+    *   [Lists]
-    *   [Style Sheet][]
+    *   [Style Sheet]
-    *   [Code Blocks][]
+    *   [Code Blocks]
-    *   [Horizontal Rules][]
+    *   [Horizontal Rules]
-*   [Span Elements][]
+*   [Span Elements]
-    *   [Links][]
+    *   [Links]
-    *   [Emphasis][]
+    *   [Emphasis]
-    *   [Code][]
+    *   [Code]
-    *   [Images][]
+    *   [Images]
-*   [Miscellaneous][]
+*   [Miscellaneous]
-    *   [Backslash Escapes][]
+    *   [Backslash Escapes]
-    *   [Automatic Links][]
+    *   [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
+Just use an empty set of square brackets (or none) -- e.g., to link the
-"Google" to the google.com web site, you could simply write:
+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
+      I get 10 times more traffic from [Google] than from
-      [Yahoo][] or [MSN][].
+      [Yahoo] or [MSN].
 
       [google]: http://google.com/        "Google"
       [yahoo]:  http://search.yahoo.com/  "Yahoo Search"