Package: wnpp Severity: wishlist * Package name : codebraid Version : 0.4.0 Upstream Author : Geoffrey Poore <gpo...@gmail.com> * URL : https://github.com/gpoore/codebraid * License : BSD 3-clause Programming Lang: Python Description : A pandoc wrapper enabling code execution in Markdown documents.
Codebraid does for Markdown documents what pythontex does for LaTeX documents, namely retrieving source code snippets in a Markdown document, running them in the relevant interpreter and inserting the results (code, text and/or graphics) in the compiled document, then processed by pandoc. This functionality allows for the creation of consistent documents collecting text, data, models, analysis code and results and discussion, thus achieving some of the goals of Reproducible Research (see https://en.wikipedia.org/wiki/Reproducibility#Reproducible_research). This tool also allows for code fragments re-use, thus allowing to decouple the explanatory text logic from the programming order, thus fullfilling some goals of literate programming (https://en.wikipedia.org/wiki/Literate_programming). These methodologies are important tools in the production of verifiable (e. g. scientific) documents, and may be important in the production of well- documented computer programs. Analogous tools already exist: Among those dedicated to the production of scientific documents, I have used the following: * D. Knuth's Web/CWeb system is the tool used to build TeX and Metafont, supporting Pascal and C code respectively, the text being LaTeX. * The R packages sweave and knitr , the latter supporting R, Python and Julia code and partially supporting a dozen other languages (no continuity between code snippets) ; the text is LaTeX. * SageTeX post-processes a LaTeX document containing Sagemath snippets (which can call about a dozen different tools and languages) and insert the results in the document, which can be re-processed. * Pythontex does the same for LaTeX documents, supporting a half-dozen source code languages. Among them, Sagemath (which was my original reason to search for an alternative to knitr/SageTeX). * knitr can also be used with Markdown text. * The Babel system of emacs' org-mode supports about 70 source code languages, using a sui generis markup language. I am also aware of the existence of various systems, each, to the best of my knowledge, dedicated to a specific task: * The Sphinx ecosystem, dedicated to the documentation of Python source code. * Pweave (ditto). Why package codebraid ? * Markdown support. Important for two reasons: - Whereas LaTeX is ideal for the production of documents ultimately aimed at printing, it is ill-adapted to producing, for example, HTML or epub documents. Parts of its cross-reference system, such as indexing, being page number based, makes no sens for, say, a presentation or an ebook. - Latex is much more heavy than Markdown, and, therefore, nowadays, much less popular. It also needs more work: While I have practisdd LaTeX since 1987, I am still forced to use the disorganised, disparate and enormous documentation of its zillions packages... * (Supposedly) easy addition of support for new source-code languages. (Note: it *seems* easy, but I am yet to do it in practice...). In comparison, adding a new language to knitr is heavy... * Independence of any editor (this one is aimed at org-mode : emacs isn't everyone's tool...). * Programming language: not everybody is expert in R or in emacs-lisp... No need to maintain an R installation (you have to maintain a Python installation, but this is a basic Debian requirement...). The cherry on my cake: in its current development version (0.5.0), codebraid supports Sagemath (http://www.sagemath.org/). TL;DR: notwithstanding Markdown's limitations (e. g. the lack of an universal cross-reference system, inconsistencies in table handling, etc...), the packaging of codebraid would offer to Debian users an important tool for the creation of consistent documents via Markdown, without involving LaTeX heavy- handedness. Note: not being an Ordained Debian Developer (C)(R)(TM), I can't package it myself. Thus this RFP.
