{"id":17987221,"url":"https://github.com/justinmeiners/srcweave","last_synced_at":"2025-03-25T22:31:34.712Z","repository":{"id":40491499,"uuid":"467382551","full_name":"justinmeiners/srcweave","owner":"justinmeiners","description":"A literate programming system for any language.","archived":false,"fork":false,"pushed_at":"2024-01-14T07:56:36.000Z","size":163,"stargazers_count":106,"open_issues_count":8,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-20T21:13:26.959Z","etag":null,"topics":["common-lisp","documentation-generator","documentation-tool","hacktoberfest","knuth","literate-programming","markdown"],"latest_commit_sha":null,"homepage":"https://www.jmeiners.com/literate-programming/","language":"Common Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justinmeiners.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-08T05:55:48.000Z","updated_at":"2025-02-21T17:00:14.000Z","dependencies_parsed_at":"2024-10-29T19:34:52.412Z","dependency_job_id":null,"html_url":"https://github.com/justinmeiners/srcweave","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinmeiners%2Fsrcweave","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinmeiners%2Fsrcweave/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinmeiners%2Fsrcweave/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinmeiners%2Fsrcweave/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justinmeiners","download_url":"https://codeload.github.com/justinmeiners/srcweave/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245554614,"owners_count":20634582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["common-lisp","documentation-generator","documentation-tool","hacktoberfest","knuth","literate-programming","markdown"],"created_at":"2024-10-29T19:07:41.724Z","updated_at":"2025-03-25T22:31:34.423Z","avatar_url":"https://github.com/justinmeiners.png","language":"Common Lisp","funding_links":[],"categories":["Common Lisp"],"sub_categories":[],"readme":"# srcweave\n\n`srcweave` is a [literate programming](https://en.wikipedia.org/wiki/Literate_programming) system for ANY programming language.\n`srcweave` helps you write code to be read by humans, not machines.\n\n**Features:**\n\n- Compatible with all programming languages. Uses markdown for prose.\n- Great support for working with multiple files (even books!). Code and prose can be moved between files seamlessly.\n- Outputs clean HTML documentation that is easy to read and customize.\n- An optional beautifier includes syntax highlighting (google-prettify) and typeset math (KaTeX).\n- Focused UNIX philosphy design. It does one thing well and plays nice with other tools like `make` (preserves mod dates).\n\n## .lit file examples\n\nThe best part about `.lit` is you learn it by just reading the code!\nHere are a few basic examples to get started with:\n\n- [Hello world](https://github.com/justinmeiners/srcweave/tree/master/tests/hello/hello.lit)\n- [Basic features](https://github.com/justinmeiners/srcweave/tree/master/tests/basic/basic.lit)\n\nFor more in-depth examples, see my article:\n\n- [Write your own Virtual Machine](https://github.com/justinmeiners/lc3-vm)\n\n## Getting started\n\n**Requirements**\n\n- `sbcl` with [quicklisp](https://quicklisp.org) installed\n- `markdown` (I recommend the `discount` implementation).\n- Recommended: A POSIX system with `sh`, `curl` and related commands for `srcweave-html-styler`.\n\n**Install**\n\nClone the project and run the following:\n\n    make\n    make install\n\n**Usage**\n\n1. Create an `index.lit` file. For example:\n\n        # Test\n\n        Test console output:\n\n        --- hello.js\n        console.log(\"Hello, World!\");\n        ---\n\n2. Run `srcweave --tangle . index.lit` to generate source files (`hello.js`).\n\n3. Run `srcweave --weave doc/ index.lit` to generate documentation (`index.html`).\n\nBoth `--tangle` and `--weave` can be included in the same invocation.\nMultiple lit files can be specified, and the order they are listed in will determine the order of chapters and sections across files.\n\n## Styling\n\nIncluded in the installation is a tool called `srcweave-html-styler` which converts default HTML into beautiful documents.\nTo use just add the `--style srcweave-html-styler` to any weave command.\nFor example:\n\n    srcweave --weave doc/ --styler srcweave-html-styler index.lit\n\nOnce for every project, you will also need to run:\n\n    srcweave-html-styler-init docs/\n\nThis downloads all the necessary JavaScript and CSS dependencies.\n\n**Math typesetting**\n\nInclude the `-m` flag on `srcweave-html-styler-init` to download KaTex.\nSee the examples for how to use `TeX` in .lit.\n\n**Custom styles**\n\nAn easy way to customize the style is to edit the CSS file created by `srcweave-html-styler-init`.\nIf that's insufficient, you are encouraged to create your own styler program.\nStylers are just programs that take raw HTML in `stdin` and format it to `stdout`.\nYou can start from scratch, or you can modify a copy of `srcweave-html-styler`.\n\n## Comparison with Literate\n\nsrcweave is inspired by Zach Yedidia's [Literate](https://zyedidia.github.io/literate/).\nI like his program, have used it for several years, and am grateful for his contribution.\nHowever, I have since developed my own preferences and ideas for improvement:\n\n- Written in Common Lisp instead of D.\n  This makes it more stable and portable (works on BSD, etc).\n- More modular UNIX design.\n  srcweave completely delegates HTML formatting and libraries to a shell script.\n  It provides high quality document output right out of the box, but is much easier to customize.\n- Simpler handling of multiple files.\n  The \"books\" feature in Literate is a little cumbersome.\n  In srcweave you can have multiple chapters in a single file,\n  or divide them each into their own file. There is no distinction.\n- GPL license instead of MIT.\n  srcweave is a program for end users.\n  GPL should not restrict commercial use of the program while maximizing user freedom (contact me if you have an issue).\n\nThe [vim plugin](https://github.com/zyedidia/literate.vim) should be compatible.\n\n**Known incompatibilities:**\n\nYou can migrate files from Literate with only minor changes.\nHere are the important differences:\n\n- Literate produces a file for any block title with a file extension (eg. \"out.txt\").\n  In srcweave, all file blocks must be prefixed with a path (eg. `/out.txt` to create `out.txt` in the working directory).\n- Styling commands like `@add_css`, `@colorscheme` are ignored.\n  All styling is done with a separate tool instead (see \"Styling\" section above).\n- No support for `@book`. Just pass multiple `.lit` files to `srcweave` in the order you want.\n- No support for `@change`. Adjusting `.lit` files should be done using your build process, such as with a shell script or makefile.\n- `@title` only sets the page title, it does not create a heading.\n- Prefer markdown headings `# heading 1`  and `## heading 2` instead of `@s`, etc.\n\n## Acknowledgments\n\nWe are very grateful to all our contributors:\n\n- [Ryan Pendleton](https://github.com/rpendleton) for designing the document styler.\n- [Eric Ihli](https://github.com/eihli) for creating an [Emacs mode](https://github.com/eihli/lit-mode) and guiding new features.\n\n## License\n\n[GPL 2](LICENSE.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinmeiners%2Fsrcweave","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustinmeiners%2Fsrcweave","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinmeiners%2Fsrcweave/lists"}