New file format: .litdiff

[paigeruten]

I don't think having the code (steps.diff) separate from the tutorial text (doc/) is ideal. I think the tutorial text should be inline with the code in the steps.diff file. That way you can write the tutorial and actually see the code of each step that you're writing about.

In the git repo representation, the tutorial text in between steps should go in the commit messages of empty commits between actual step commits. So the git repo contains the entire tutorial, like a gitorial, and you can reorder bits of the tutorial text at the same time as you reorder the steps in the tutorial using rebase.

Step commits can also have tutorial text in the commit message, which could be rendered differently from text that isn't associated with a particular step. I'm thinking the first line of the commit message could serve as a summary/name for each step, which could optionally be rendered as part of each step in the tutorial output. Then the text below that would be the paragraph(s) that explain the step in detail, which could be rendered either above or below the diff in the rendered tutorial.

The steps.diff file should be splittable into multiple files, so you can have one file per chapter for example. I'm thinking of using the file extension .litdiff, for "literate diff", similar to CoffeeScript's .litcoffee. So you'd have 01-setup.litdiff, 02-enteringRawMode.litdiff, 03-rawInputAndOutput.litdiff, etc.

Currently, the diff for each step in steps.diff begins with a ~~~ step: line, and continues until the first completely blank line (even blank lines in diffs have a space character at the beginning). So it should be fine to just have tutorial text in between steps, with no special formatting or markup or anything. There will need to be a way of associating paragraph(s) with a particular step though. A paragraph coming after a step might be explaining that step, or it could be explaining the next step, or it could be segueing from one step to the next in which case it shouldn't be tied to either step. If it's tied to a step, then the paragraph(s) should appear in the git commit message for that step, otherwise it should appear in the git commit message of an empty commit between those steps. So, we do need some kind of markup to say whether a paragraph is associated with a particular step. (It matters because you might want to render a tutorial in a very structured way, for example displaying only a single step per page, in which case you'd only want to show the text associated with that step on that step's page.)

OK, this is getting lengthy, this is just me getting a bunch of ideas down. This'll hopefully become a lot more clear and concise after I've had time to think about it some more. To summarize what needs to be done:

• [x] Don't bother with the steps/ step folders representation for now. Just remove it.
  • [x] Make doc command use repo/ instead of depending on steps/.
• [x] Also remove a bunch of other commands/code that's no longer needed.
• [x] Better code for converting between repo/ and steps.litdiff representations.
  • [x] repo/ -> litdiff
  • [x] litdiff -> repo/
• [x] Specify .litdiff file format
  • [x] Figure out a minimalist way of associating paragraphs and step summaries with steps
• [x] Allow .litdiff to be split into multiple files
  • [x] Figure out how the order should be specified (just by filename?)
  • [x] Figure out how to represent the split in the git representation
• [x] More flexible HTML templates for rendering this stuff
  • [x] Split Diff class + doc command code into cleaner modules: (1) diff parser, (2) diff transformers, (3) diff renderer, (4) HTML templates.

Most of the above is done! Just lots of little (some not so little) things to get done now:

• [x] Copy the rest of kilo-tutorial's text from doc/*.md to the *.leg files.
• [x] Maybe use .litdiff extension instead of .leg
• [x] Put .litdiff files in diff/ folder
• [ ] Figure out how to use a layout template for both "chapter" pages and "static" pages
• [x] Somehow allow the content of static pages to be written in markdown
• [x] Allow step diffs to be rendered on demand anywhere in the tutorial, and/or via ERB
• [ ] Why is kilo's Makefile not being highlighted right anymore?
• [x] Figure out how to bring back the "tags" for each step in kilo ("this step compiles", "this step doesn't compile", etc.)
• [x] Decide what variables to expose to templates, and make it consistent (especially w/r/t @config. Maybe leg.yml should be replaced altogether by some kind of front matter inline with the tutorial? Just make everything inline?)
• [x] De-duplicate the code for walking through the repo/ (and a lot of the logic inside the loop)
• [ ] Bring back progress indicators
• [ ] Update default templates after finalizing what gets sent to templates
• [ ] Support automatic creation of .zip file again
• [x] Diff transformers
  • [x] Section folding should be done by a diff transformer that looks for section start/end patterns and replaces the lines of unchanged sections with a single DiffLine of type :folded.
  • [x] The "omit adjacent removals" transformer
  • [x] Make sure blank lines are still handled smartly
• [ ] Support two output formats for leg doc: HTML and Markdown (in case people want to just throw a tutorial onto GitHub, or their blog)
• [ ] Should make leg doc skinny, and allow the same functionality to be invoked by using snaptoken as a library in a Ruby script.
• [ ] Figure out better way of specifying the order of .litdiff files
• [ ] See if the leg doc command can be optimized (wait until we have diff transformers to shorten the diffs first, that will make a huge difference (syntax highlighting is probably the bottleneck))
• [ ] Figure out a good and safe workflow for switching between working with the litdiff and repo formats (could get a last modified date for both of them, and also record which one was last converted to the other, and warn the user when they might be overwriting their work).
• [ ] Maybe think of a better way to define pages (their filenames, titles, and order)
• [ ] When all of the above is done, do a close compare of the currently deployed tutorial and the newly-rendered tutorial (should be able to automatic this actually, by normalizing the HTML and just doing a diff on that?)

Branch: litdiff Parallel branch for converting kilo-tutorial to litdiff: https://github.com/snaptoken/kilo-tutorial/tree/litdiff

[paigeruten]

Closing this and creating new issues for each unchecked todo item.