Code blocks in spec

[yiannisbot]

We need to make a decision on the best way to include code in the spec.

The requirements for this are:

1. the lotus version of the code should be present in the spec (this will be the Go code as agreed in https://github.com/filecoin-project/specs/issues/998 - at least for now)
2. the code presented in the specs site should be up to date.

The options we have for the first point are:

• include blocks of code in the corresponding sections. IMO, this breaks the flow and disrupts attention as code blocks are very often very long. An alternative is to do some css magic (suggested by @olizilla) and include code in "scrollable" windows/frames in each section. In this case, we would have up to "includeHeight" lines of code directly visible in the window/frame and the rest would be "scrollable". This has the advantage of both having the code in place, but also avoid having endless blocks of code within the section.
• include the code blocks in a the "Listings" section and link to each listing from the corresponding section in the main spec. This again provides easy access to the code block without being disruptive to the text of the specification.

The only option I see for the second point, which will meet our requirement without incurring extra manual effort is to pull the corresponding .go files from the main repositories and rebuild the site every some amount of time (say every 1h/1d). Another less optimal option is to manually copy the .go files on "code freeze" to the specs repo. In the future, this means that any changes to the main code will have to be updated manually on the specs repo, or otherwise the specs version of the code will run out of date.

Until we start working towards the vision of "compilable" spec site, these options look reasonable to me. It would be great if we can reach a decision asap.

cc: @whyrusleeping @anorth @schomatis @daviddias

[anorth]

Could we just link to the Lotus code?

IMO copy-pasting code verbatim from Lotus is just going to open a new maintenance problem. What's the point if it's just supposed to match exactly? Just own up to having a reference implementation, until we actually do protocol design in the spec instead of the implementations.

High-level pseudocode could be more valuable and less a maintenance problem (but still a real one).

But I'm not the owner here, so don't let my objections block progress.