Package: slit
Aboutslit, orsequential lit, is a literate programming tool for creating
compelling, accurate software tutorials with minimal effort.slit borrows from the school of literate programming, where programs are
generated from their own documentation. However, where other tools focus
onwhata program is, slit focuses onhowa program is written, and
provides a richer syntax for expressing thesequenceof a program’s
creation from start to finish.In doing so, slit turns literate programming into an unstoppable tool
for creating compelling, provably accurate programming tutorials.FeaturesTotal control of code and documentation structurein timeCarefully document every single step, including wrong turns,
backtracking, and extending existing codeGenerateworking, complex, multi-file, multi-language program
examples from a single tutorialOutput shell commands directly into your documentation to show the
progression of a programWho uses slit?slit is at the core of theLameStation programming
tutorials(in development).The README you are reading right now is generated with./slit-sREADME.lit.Installingslitis a single python script and has been tested with Python 2.7.UsageWhile trying to keep new syntax to a minimum, slit adds some extremely
useful features that are hard to find.Basicsslit uses markdown for its documentation format, but works with any
programming language.slit files should be marked with with.litextension, appended to
the regular file extension.hello_world.c.litslit works by allow you to assemble code into separate containers, then
building your document from them.Code containers are marked with the<< blockname >>=syntax on a
line by itself. They must be indented to be accepted as code macros.Here is our hello world example!

    << main >=
    int main (void)
    {
        printf("hello world!\n");
    }The code block will end when the indent level returns to 0.printf("hello world!\n");
    }

The code block is over!Basic macrosThere are three core elements that make up slit syntax.Macro assignment -<< NAME >>=Macro append -<< NAME>>+=Macro value -<< NAME >>append macroThe append macro (<< NAME>>+=) allows you to add code to the end of
a new or existing container, whereNAMEis the container name.assignment macroThe assignment macro (<< NAME >>=) will add code to a new or
existing container, overwriting what was already in it, whereNAMEis the container name.container namesContain names can be one of the followingNamed containers, containing alphanumeric characters and underscores,
likecodeblock1,main_function.File containers, containing a single-word filename with extension,
likefilename.txt(files with spaces or that reside in a
different path are not currently supported)The*container, which will create a file named after the
top-level slit file with the.litextension removed. So forhello_world.c.lit, the*container will generate thehello_world.ccode file.The top-level documentation file is always generated at the source file
name with a.mdextension, sohello_world.c.litwill generatehello_world.c.mdInclude directiveUse the#includedirective to organize a single tutorial into
multiple files.#include "part1.spin"
#include "part1.diagram"
#include "part2.spin"
#include "part2.diagram"
#include "gfx_cave.lit"
#include "conclusion.md"Shell commandsWARNING: this WILL allow tutorials to execute commands directly on
your system. Use with caution.Use the shell macro (<<#!command >>) to dump the output of shell
commands into your tutorial.Watch the output of the<<#!tree test/ >>command.$ tree test/
test/
├── bacon
├── chicken
└── turkey

0 directories, 3 filesThis feature is inherently platform and build environment dependent and
will make your tutorial build less portable. Use wisely!This feature is disabled by default. Enable with-s.More infoFor a complete listing of slit parameters, use--help:$ ./slit --help
usage: slit [-h] [-s] [-c] PATH [PATH ...]

A sequential literate processor.

positional arguments:
  PATH           path to lit file to process (dir or file)

optional arguments:
  -h, --help     show this help message and exit
  -s, --shell    enable shell code execution
  -c, --convert  create lit file from sourceAuthorslit is created by Brett Weir, and inspired by Connor Osborne’slittool and Donald Knuth, for
coming up with literate programming in the first place.Bug ReportingPlease report all bugs to theslit issue
tracker.