Merge pull request #112 from justindujardin/urlrefs

Issue #100 Fix (URL References across sections)

src/docco.coffee

@@ -100,8 +100,8 @@ parse = (source, code) ->
 # and runs the text of its corresponding comment through **Markdown**, using
 # [Showdown.js](http://attacklab.net/showdown/).
 #
-# We process the entire file in a single call to Pygments by inserting little
-# marker comments between each section and then splitting the result string
+# We process the entire file in single calls to Pygments and Showdown by inserting 
+# little marker comments between each section and then splitting the result string
 # wherever our markers occur.
 highlight = (source, sections, callback) ->
   language = getLanguage source
@@ -110,11 +110,13 @@ highlight = (source, sections, callback) ->
     '-f', 'html',
     '-O', 'encoding=utf-8,tabsize=2'
   ]
-  output   = ''
+  output = ''
+  code = (section.codeText for section in sections).join language.codeSplitText
+  docs = (section.docsText for section in sections).join language.docsSplitText
 
   pygments.stderr.on 'data',  (error)  ->
     console.error error.toString() if error
-    
+
   pygments.stdin.on 'error',  (error)  ->
     console.error 'Could not use Pygments to highlight the source.'
     process.exit 1
@@ -124,15 +126,16 @@ highlight = (source, sections, callback) ->
 
   pygments.on 'exit', ->
     output = output.replace(highlightStart, '').replace(highlightEnd, '')
-    fragments = output.split language.dividerHtml
+    codeFragments = output.split language.codeSplitHtml
+    docsFragments = showdown.makeHtml(docs).split language.docsSplitHtml
+
     for section, i in sections
-      section.codeHtml = highlightStart + fragments[i] + highlightEnd
-      section.docsHtml = showdown.makeHtml section.docsText
+      section.codeHtml = highlightStart + codeFragments[i] + highlightEnd
+      section.docsHtml = docsFragments[i]
     callback()
 
   if pygments.stdin.writable
-    text = (section.codeText for section in sections)
-    pygments.stdin.write text.join language.dividerText
+    pygments.stdin.write code
     pygments.stdin.end()
 
 # Once all of the code is finished highlighting, we can generate the HTML file by
@@ -186,12 +189,20 @@ for ext, l of languages
 
   # The dividing token we feed into Pygments, to delimit the boundaries between
   # sections.
-  l.dividerText = "\n#{l.symbol}DIVIDER\n"
+  l.codeSplitText = "\n#{l.symbol}DIVIDER\n"
 
-  # The mirror of `dividerText` that we expect Pygments to return. We can split
+  # The mirror of `codeSplitText` that we expect Pygments to return. We can split
   # on this to recover the original sections.
   # Note: the class is "c" for Python and "c1" for the other languages
-  l.dividerHtml = ///\n*<span\sclass="c1?">#{l.symbol}DIVIDER<\/span>\n*///
+  l.codeSplitHtml = ///\n*<span\sclass="c1?">#{l.symbol}DIVIDER<\/span>\n*///
+
+  # The dividing token we feed into Showdown, to delimit the boundaries between
+  # sections.
+  l.docsSplitText = "\n##{l.name}DOCDIVIDER\n"
+
+  # The mirror of `docsSplitText` that we expect Showdown to return. We can split
+  # on this to recover the original sections.
+  l.docsSplitHtml = ///<h1>#{l.name}DOCDIVIDER</h1>///
 
 # Get the current language we're documenting, based on the extension.
 getLanguage = (source) -> languages[path.extname(source)]

test/tests.coffee

@@ -83,4 +83,24 @@ test "single line comment parsing", ->
 
   # *Kick off the first language test*
   testNextLanguage languageKeys.slice()
-
+
+# **URL references should resolve across sections**
+#  
+# Resolves [Issue 100](https://github.com/jashkenas/docco/issues/100)
+test "url references", ->
+  exec "mkdir -p #{dataPath}", ->
+    sourceFile = "#{dataPath}/_urlref.coffee"
+    fs.writeFileSync sourceFile, [
+      "# Look at this link to [Google][]!",
+      "console.log 'This must be Thursday.'",
+      "# And this link to [Google][] as well.",
+      "console.log 'I never could get the hang of Thursdays.'",
+      "# [google]: http://www.google.com"
+    ].join('\n')
+    outPath = path.join dataPath, "_urlreferences"
+    outFile = "#{outPath}/_urlref.html"
+    exec "rm -rf #{outPath}", ->
+      Docco.document [sourceFile], output: outPath, ->
+        contents = fs.readFileSync(outFile).toString()
+        count = contents.match ///<a\shref="http://www.google.com">Google</a>///g
+        eq count.length, 2, "find expected (2) resolved url references"