{ "info": { "author": "Brett Weir", "author_email": "brett@lamestation.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "License :: OSI Approved :: GNU General Public License v3 (GPLv3)", "Programming Language :: Python :: 2.7", "Topic :: Documentation", "Topic :: Software Development :: Pre-processors", "Topic :: Text Processing", "Topic :: Text Processing :: Markup" ], "description": "slit - *sequential lit*\n=======================\n\nAbout\n-----\n\nslit, or *sequential lit*, is a literate programming tool for creating\ncompelling, accurate software tutorials with minimal effort.\n\nslit borrows from the school of literate programming, where programs are\ngenerated from their own documentation. However, where other tools focus\non *what* a program is, slit focuses on *how* a program is written, and\nprovides a richer syntax for expressing the *sequence* of a program's\ncreation from start to finish.\n\nIn doing so, slit turns literate programming into an unstoppable tool\nfor creating compelling, provably accurate programming tutorials.\n\nFeatures\n~~~~~~~~\n\n- Total control of code and documentation structure *in time*\n\n- Carefully document every single step, including wrong turns,\n backtracking, and extending existing code\n\n- Generate **working**, complex, multi-file, multi-language program\n examples from a single tutorial\n\n- Output shell commands directly into your documentation to show the\n progression of a program\n\nWho uses slit?\n~~~~~~~~~~~~~~\n\n- slit is at the core of the `LameStation programming\n tutorials `__\n (in development).\n\n- The README you are reading right now is generated with\n ``./slit -s README.lit``.\n\nInstalling\n----------\n\n``slit`` is a single python script and has been tested with Python 2.7.\n\nUsage\n-----\n\nWhile trying to keep new syntax to a minimum, slit adds some extremely\nuseful features that are hard to find.\n\nBasics\n~~~~~~\n\nslit uses markdown for its documentation format, but works with any\nprogramming language.\n\nslit files should be marked with with ``.lit`` extension, appended to\nthe regular file extension.\n\n::\n\n hello_world.c.lit\n\nslit works by allow you to assemble code into separate containers, then\nbuilding your document from them.\n\nCode containers are marked with the ``<< blockname >>=`` syntax on a\nline by itself. They must be indented to be accepted as code macros.\n\n::\n\n Here is our hello world example!\n\n << main >=\n int main (void)\n {\n printf(\"hello world!\\n\");\n }\n\nThe code block will end when the indent level returns to 0.\n\n::\n\n printf(\"hello world!\\n\");\n }\n\n The code block is over!\n\nBasic macros\n~~~~~~~~~~~~\n\nThere are three core elements that make up slit syntax.\n\n- Macro assignment - ``<< NAME >>=``\n\n- Macro append - ``<< NAME >>+=``\n\n- Macro value - ``<< NAME >>``\n\nappend macro\n^^^^^^^^^^^^\n\nThe append macro (``<< NAME >>+=``) allows you to add code to the end of\na new or existing container, where ``NAME`` is the container name.\n\nassignment macro\n^^^^^^^^^^^^^^^^\n\nThe assignment macro (``<< NAME >>=``) will add code to a new or\nexisting container, overwriting what was already in it, where ``NAME``\nis the container name.\n\ncontainer names\n^^^^^^^^^^^^^^^\n\nContain names can be one of the following\n\n- Named containers, containing alphanumeric characters and underscores,\n like ``codeblock1``, ``main_function``.\n\n- File containers, containing a single-word filename with extension,\n like ``filename.txt`` (*files with spaces or that reside in a\n different path are not currently supported*)\n\n- The ``*`` container, which will create a file named after the\n top-level slit file with the ``.lit`` extension removed. So for\n ``hello_world.c.lit``, the ``*`` container will generate the\n ``hello_world.c`` code file.\n\nThe top-level documentation file is always generated at the source file\nname with a ``.md`` extension, so ``hello_world.c.lit`` will generate\n``hello_world.c.md``\n\nInclude directive\n~~~~~~~~~~~~~~~~~\n\nUse the ``#include`` directive to organize a single tutorial into\nmultiple files.\n\n::\n\n #include \"part1.spin\"\n #include \"part1.diagram\"\n #include \"part2.spin\"\n #include \"part2.diagram\"\n #include \"gfx_cave.lit\"\n #include \"conclusion.md\"\n\nShell commands\n~~~~~~~~~~~~~~\n\n**WARNING: this WILL allow tutorials to execute commands directly on\nyour system. Use with caution.**\n\nUse the shell macro (``<<#! command >>``) to dump the output of shell\ncommands into your tutorial.\n\nWatch the output of the ``<<#! tree test/ >>`` command.\n\n::\n\n $ tree test/\n test/\n \u251c\u2500\u2500 bacon\n \u251c\u2500\u2500 chicken\n \u2514\u2500\u2500 turkey\n\n 0 directories, 3 files\n\nThis feature is inherently platform and build environment dependent and\nwill make your tutorial build less portable. Use wisely!\n\nThis feature is disabled by default. Enable with ``-s``.\n\nMore info\n~~~~~~~~~\n\nFor a complete listing of slit parameters, use ``--help``:\n\n::\n\n $ ./slit --help\n usage: slit [-h] [-s] [-c] PATH [PATH ...]\n\n A sequential literate processor.\n\n positional arguments:\n PATH path to lit file to process (dir or file)\n\n optional arguments:\n -h, --help show this help message and exit\n -s, --shell enable shell code execution\n -c, --convert create lit file from source\n\nAuthor\n------\n\nslit is created by Brett Weir, and inspired by Connor Osborne's\n`lit `__ tool and Donald Knuth, for\ncoming up with literate programming in the first place.\n\nBug Reporting\n-------------\n\nPlease report all bugs to the `slit issue\ntracker `__.", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/bweir/slit", "keywords": "lit literate programming sequential tutorial education software", "license": "GPLv3", "maintainer": null, "maintainer_email": null, "name": "slit", "package_url": "https://pypi.org/project/slit/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/slit/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/bweir/slit" }, "release_url": "https://pypi.org/project/slit/0.2.0/", "requires_dist": null, "requires_python": null, "summary": "A sequential lit tool", "version": "0.2.0" }, "last_serial": 1555954, "releases": { "0.1.0": [ { "comment_text": "", "digests": { "md5": "a3213b5c7015f748c0d9b6e87971a9cc", "sha256": "7f94f5ddc5dd37bb9008b7ad42a561e423cd6a5c2e05426800b71aa1539c0aa8" }, "downloads": -1, "filename": "slit-0.1.0.tar.gz", "has_sig": false, "md5_digest": "a3213b5c7015f748c0d9b6e87971a9cc", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 6345, "upload_time": "2015-04-17T08:05:59", "url": "https://files.pythonhosted.org/packages/ef/ad/923aabb452f9bdb105ebea6a22e2b355a1916d004a714c045f19f957775b/slit-0.1.0.tar.gz" } ], "0.2.0": [ { "comment_text": "", "digests": { "md5": "2e07033cda0956a9808c4a29e5c8be6b", "sha256": "4d770123644109ba85ee49d3f43907b64e75e9c5084287e667c7c724e556d168" }, "downloads": -1, "filename": "slit-0.2.0.tar.gz", "has_sig": false, "md5_digest": "2e07033cda0956a9808c4a29e5c8be6b", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 6305, "upload_time": "2015-05-21T03:09:23", "url": "https://files.pythonhosted.org/packages/95/25/ad2f55519dc0e2fa86832c94d69e1ad40d3ff6db4a3d91596ce01eb697f7/slit-0.2.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "2e07033cda0956a9808c4a29e5c8be6b", "sha256": "4d770123644109ba85ee49d3f43907b64e75e9c5084287e667c7c724e556d168" }, "downloads": -1, "filename": "slit-0.2.0.tar.gz", "has_sig": false, "md5_digest": "2e07033cda0956a9808c4a29e5c8be6b", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 6305, "upload_time": "2015-05-21T03:09:23", "url": "https://files.pythonhosted.org/packages/95/25/ad2f55519dc0e2fa86832c94d69e1ad40d3ff6db4a3d91596ce01eb697f7/slit-0.2.0.tar.gz" } ] }