saivann/bitcoin.org — pull request #51 by harding (2014-04-10 02:03:50+00:00)
Title: Auto Cross-Reference Proof Of Concept

@saivann made an excellent suggestion that we automatically add cross references. This would keep the source text cleaner and also save us from rote manual linking, so I played around with Jekyll a little bit to see what it could do.

The three methods I could think of all stunk[1], so I chose the least stinky: a Liquid block-level plugin like the syntax highlight plugin. To use it, you simply surround the text you want to auto cross-reference with a tag like this (but switch brackets to braces):

[% autocrossref %]
The block chain is made of blocks!
[% endautocrossref %]

Which will automatically add Markdown-style links for any terms we've defined. For example (switch parens to brackets):

The (block chain)() is made of blocks(block)!

The following pull request is a proof-of-concept for this idea. Your feedback is essential to determine whether or not I go through and update all the links I manually made just last weekend.

1. Take a look at the changes to en/developer-guide.md in the pull request to see how it would work. (I've only done the first two subsections of the block chain.)

2. Take a look at [my Jekyll preview](http://test.dtrt.org/en/developer-guide.html) to see it in action. (It looks a lot like the old cross refs, except now it's automatic.)

3. Take a look at the code I wrote. I'm not a ruby coder, so I won't feel bad at all if you find mistakes/horrible inefficiencies.

Here's some possible problems with auto cross-referencing:

* To prevent conflicts with Markdown style and Kramdown extras, auto cross-referencing will not work inside [brackets] or {braces}. I don't think that's a problem. It will work just fine inside (parens).

* To prevent conflicts with images, auto cross-referencing will not work in front of the literal text ".svg" or ".png" unless those strings appear inside Markdown image tags. That means we cannot use .svg or .png outside image tags. I don't think that's a problem. (If it is, we can tighten the regular expression.)

* More problematic, auto cross-ref will turn \`block\` into `[block][]`. To prevent this, we need to explicitly create an alias for \`block\` or move it outside of an autocrossref..endautocrossref block. More code could fix this if it becomes a real problem.

* Every sentence needs to end with punctuation or you could get some weird effects. For example, the end of this list item could be combined with the next paragraph if we did this: RFC1234 is a standard

Transactions are cool

Now this message is almost as long as my diff, so I'll stop writing. Feedback appreciated.

-Dave

[1] The three methods to modify text are (1) global modification of Markdown source; (2) global modification of HTML output; (3) selective modification of manually-selected Markdown blocks (the option chosen). Option 1 requires practically writing a Markdown interpreter so you don't add links to headers, code blocks, and other places. Option 2 denies us the power of Markdown links, increasing our link maintenance work. Option 3 made the most sense to me.