See also

lib/parser.js

@@ -1,6 +1,7 @@
 var last = require('lodash.last');
 var unescape = require('lodash.unescape');
 var marked = require('marked');
+var index = require('./index');
 
 var allElements = [
   'blockquote', 'html', 'strong', 'em', 'br', 'del',
@@ -9,7 +10,7 @@ var allElements = [
 ];
 
 function unhtml(text){
-  text = text.replace(/<code>/, '').replace(/<\/code>/, '');
+  // text = text.replace(/<code>/, '').replace(/<\/code>/, '');
   return unescape(text);
 }
 
@@ -18,7 +19,8 @@ exports.parse = function(markdown) {
   var page = {
     name: '',
     description: '',
-    examples: []
+    examples: [],
+    seeAlso: []
   };
 
   var r = new marked.Renderer();
@@ -28,33 +30,59 @@ exports.parse = function(markdown) {
     r[e] = function() { return ''; };
   });
 
-  // paragraphs just pass through (automatically created by new lines)
-  r.paragraph = function(text) {
-    if (/^<code>.*<\/code>$/.test(text)) {
-      var example = last(page.examples);
-      if (example) {
-        example.code = unhtml(text);
+  r.codespan = function(text) {
+    if (index.hasPage(text) && text !== page.name) {
+      if (page.seeAlso.indexOf(text) < 0) {
+        page.seeAlso.push(text);
       }
     }
+    var example = last(page.examples);
+    if (example) {
+      example.code = unhtml(text);
+    }
+    return text;
+  };
+
+
+  // paragraphs just pass through (automatically created by new lines)
+  r.paragraph = function(text) {
+    // if (/^<code>.*<\/code>$/.test(text)) {
+    //   var example = _.last(page.examples);
+    //   if (example) {
+    //     example.code = unhtml(text);
+    //   }
+    // } else {
     return text;
+    // }
   };
 
+  // r.paragraph = function(text) {
+  //   return text;
+  // };
+
   r.heading = function(text, level) {
     if (level === 1) {
       page.name = text.trim();
     }
+    return text;
   };
 
   r.blockquote = function(text) {
     page.description += unhtml(text);
+    return text;
   };
 
   r.listitem = function(text) {
-    page.examples.push({});
-    last(page.examples).description = unhtml(text);
+    page.examples.push({
+      description: unhtml(text)
+    });
+    return text;
   };
 
-  marked(markdown, {renderer: r, sanitize: true});
+  marked(markdown, {
+    renderer: r,
+    sanitize: true
+  });
 
   page.examples = page.examples.filter(function(example) {
     return example.description && example.code;

lib/render.js

@@ -21,6 +21,12 @@ exports.toANSI = function(page) {
     output.push('');
   });
 
+  if (page.seeAlso && page.seeAlso.length > 0) {
+    output.push('');
+    output.push('See also: ' + page.seeAlso.join(', '));
+    output.push('');
+  }
+
   return '\n' + output.join('\n') + '\n';
 };
 

test/parser.spec.js

@@ -1,4 +1,6 @@
 var parser = require('../lib/parser');
+var sinon = require('sinon');
+var index = require('../lib/index');
 
 describe('Parser', function() {
 
@@ -135,4 +137,55 @@ describe('Parser', function() {
     page.examples[3].code.should.eql('bc <<< "1 + 1"');
   });
 
+  describe('See also section', function() {
+
+    beforeEach(function() {
+      var hasPage = sinon.stub(index, 'hasPage');
+      hasPage.withArgs('lsb_release').returns(true);
+      hasPage.withArgs('ln').returns(true);
+      hasPage.withArgs('cp').returns(false);
+      hasPage.withArgs('mv').returns(false);
+    });
+
+    afterEach(function() {
+      index.hasPage.restore();
+    });
+
+    it('should parse seeAlso commands when mentioned in description', function() {
+      var page = parser.parse(
+        '\n# uname' +
+        '\n> See also `lsb_release`, `mv`'
+      );
+      page.seeAlso.should.eql(['lsb_release']);
+    });
+
+    it('should parse seeAlso commands when mentioned in examples', function() {
+      var page = parser.parse(
+        '\n# uname' +
+        '\n> Description for uname' +
+        '\n' +
+        '\n- example 1, see `ln` for details' +
+        '\n' +
+        '\n`cmd1 --foo`'
+      );
+      page.seeAlso.should.eql(['ln']);
+    });
+
+    it('should have only unique seeAlso commands when mentioned a few times', function() {
+      var page = parser.parse(
+        '\n# uname' +
+        '\n> Description for uname, see `lsb_release`, `ln`' +
+        '\n' +
+        '\n- example 1, see `ln`, `lsb_release` for details' +
+        '\n' +
+        '\n`cmd1 --foo`' +
+        '\n' +
+        '\n- example 2, see `ln` for details' +
+        '\n' +
+        '\n`cmd1 --foo`'
+      );
+      page.seeAlso.should.eql(['lsb_release', 'ln']);
+    });
+  });
+
 });

test/render.spec.js

@@ -47,4 +47,21 @@ describe('Render', function() {
     text.should.containEql(' bye'.blackBG.red);
   });
 
+  it('should correctly render see also section', function() {
+    var text = render.toANSI({
+      name: 'uname',
+      description: 'Description for `uname`.\n' +
+                   'See also `lsb_release`.',
+      examples: [{
+        description: '1st example. You need `sudo` to run this',
+        code: 'uname {{token}}'
+      }],
+      seeAlso: [
+        'lsb_release',
+        'sudo'
+      ]
+    });
+    text.should.containEql('See also: lsb_release, sudo');
+  });
+
 });