{"id":16572304,"url":"https://github.com/jonocarroll/literate","last_synced_at":"2026-01-27T18:40:04.675Z","repository":{"id":71014070,"uuid":"62185292","full_name":"jonocarroll/literate","owner":"jonocarroll","description":"Taking literate programming one step further, down into the code itself","archived":false,"fork":false,"pushed_at":"2016-07-06T12:26:52.000Z","size":42,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-16T02:53:18.354Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonocarroll.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2016-06-29T01:20:42.000Z","updated_at":"2016-06-29T01:36:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"f15d2cda-4cae-4c5a-b11c-91f71ae2a7b3","html_url":"https://github.com/jonocarroll/literate","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/jonocarroll%2Fliterate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonocarroll%2Fliterate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonocarroll%2Fliterate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonocarroll%2Fliterate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonocarroll","download_url":"https://codeload.github.com/jonocarroll/literate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242040101,"owners_count":20061980,"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":[],"created_at":"2024-10-11T21:27:06.633Z","updated_at":"2026-01-27T18:39:59.632Z","avatar_url":"https://github.com/jonocarroll.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# literate\r\n\r\n## Motivation:\r\n\r\nThis came as a flurry of inspiration while watching Donald Knuth's presentation on literate programming at useR 2016. He mentioned that while R has nice ways of incorporating comments within code (and vice versa) for a separate document (e.g. knitr), it didn't quite follow his paradigm of creating \"simple modules linked in simple ways\" for self-sufficient, self-documented, self-contained code. We also have roxygen for generating documentation, but this still occurs outside of the function in the function header.\r\n\r\nThe idea struck me: why can't we have documentation *right inside the code* and be able to browse/wander/follow through that with hyperlinks?\r\n\r\n## Proof of concept:\r\n\r\nThis proof-of-concept takes things one step further; generate some deeper documentation *inside* the code itself, and produce some (hopefully) fully self-documented functions that can be walked through via hyperlinks. This is of interest to someone who wants to know **how/why the code works**, not just **how to use it**. Achieving this requires minimal additional markup within the function body, for now denoted by `#%` blocks. These can span multiple lines, but must follow this structure:\r\n\r\n```\r\n#%{tagname}{tagbody}{nexttag}\r\n```\r\n\r\nwhere:\r\n + `tagname` denotes the tag/heading for this block (this will appear as a link and a heading).\r\n + `tagbody` describes the part of the code that follows. Not what, but why. This can include links to other tagged sections using `%%othertag ` (must be followed by a space, not the end of the delimited block).\r\n + `nexttag` denotes the next piece of code in sequence (this will appear as a link to that block).\r\n\r\nNone of these may contain either `{` or `}` as this breaks the above structure (can't deal with escaping yet). Additionally though, `%%othertag` can appear anywhere in the code comments (e.g. also in inline comments) to refer to a literate code block. This could be very helpful for explaining reasoning behind a coding choice. For example\r\n\r\n```\r\ny \u003c- 2 * x # this choice motivated by %%scale\r\n```\r\n\r\nThese `%%othertag`s will be converted to links in the processed output, resulting in\r\n\r\n```\r\ny \u003c- 2 * x # this choice motivated by \u003ca href=\"#scale\"\u003escale\u003c/a\u003e\r\n```\r\n\r\n## Example:\r\n\r\nThe [`literate.ks.test()`](https://github.com/jonocarroll/literate/blob/master/literate.ks.test.R) function uses a few trivial blocks to show what I mean. In reality, these would contain the 'why' of the block of code, linking to related parts of the code. There probably shouldn't be too many of these blocks in your function; if there are, maybe it's too complex and could be broken down into several smaller functions?\r\n\r\n```\r\n  #%{checking}{perform input checking. \r\n  #% This comment is very long\r\n  #% and spans multiple lines. Processing needs \r\n  #% to be able to handle this.}{basecase}\r\n  alternative \u003c- match.arg(alternative)\r\n```\r\n\r\nIn the above `checking` block, the description (trivial for now) would describe why certain cases are being tested, or why certain conditions are likely to be encountered. This might even link to a `%%conditionalreturn` block. The `basecase` tag refers to the next piece of code to be evaluated in sequence.\r\n\r\n## Installation:\r\n\r\nFor now, this is not quite a package, but it's coming along. Purely proof of concept on the one file for now.\r\n\r\n## Usage:\r\n\r\nAfter evaluating the [`process_literate()`](https://github.com/jonocarroll/literate/blob/master/literate.R) function, and a literate-programmed function (e.g. taking Donald Knuth's example, [`literate.ks.test()`](https://github.com/jonocarroll/literate/blob/master/literate.ks.test.R)), the literate view can be generated with\r\n\r\n```\r\nprocess_literate(\"literate.ks.test\")\r\n```\r\n\r\nwhere the only argument is the quoted name of the literate function to be processed. `process_literate` will extract the literate-specific blocks, generate links, save as a temporary .html file (via `tempfile`) and load the processed HTML into a browser via `browseURL`.\r\n\r\n[The results for this example are shown here](http://jonocarroll.github.io/literate/).\r\n\r\nSince the literate blocks are all commented, there should be no impact on non-literate-programming functions, in which case it should just open a browser to the original code. At the moment that's broken (edge case).\r\n\r\n## Ideas for going forward:\r\n\r\n + Fix the edge case where there is no literate markup, in which case this currently fails. (easy)\r\n + add a table of contents of all literate links. (easy)\r\n + better processing of the tags with more sophisticated regex. (moderate)\r\n + CSS styling on the links to distinguish them from the code, and add top/bottom jumps. (moderate)\r\n + Use a monospace font specifically for output. (easy)\r\n + htmlify the remainder of the function body. (easy)\r\n + find out how to hook into the internal RStudio browser. (hard)\r\n + build a better example case. (easy)\r\n + `%%` is not a particularly protected choice, and perhaps something else would be better. (moderate)\r\n + this list will eventually be in [Issues](https://github.com/jonocarroll/literate/issues). (easy)\r\n + include links to GitHub issues right in the comments. (easy)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonocarroll%2Fliterate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonocarroll%2Fliterate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonocarroll%2Fliterate/lists"}