You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/ieee-escience-paper.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -63,7 +63,7 @@ The source code for the literate computer program is contained in code blocks th
63
63
64
64
It is tempting to argue that literate programming is the best approach for any programming task. However, when it comes to pure utilitarian software development, that argument becomes increasingly harder to make. In this paper we take a more modest goal of arguing for literate programming in the scientific domain. There are some distinct features of scientific programming that make it worth to invest in a more human representation than most programming languages allow for. After all, science is a human endeavor for better understanding the world around us.
65
65
66
-
Software is used in many different ways in research, so there are different types of research software (see @rob2023for an overview). Distinction can be made between software found inside instruments, software used for modelling, analysis, visualization, or tying together different components (i.e. workflow systems). These areas of application vary in their degree of being a direct method leading to a scientific result versus pure engineering applications. The following discussion applies mostly to the former, and may be best read as limiting to modelling and analysis.
66
+
Software is used in many different ways in research, so there are different types of research software (see van Nieuwpoort and Katz (2023) for an overview[@rob2023]). Distinction can be made between software found inside instruments, software used for modelling, analysis, visualization, or tying together different components (i.e. workflow systems). These areas of application vary in their degree of being a direct method leading to a scientific result versus pure engineering applications. The following discussion applies mostly to the former, and may be best read as limiting to modelling and analysis.
67
67
68
68
So the question is then, what makes research software different than other software? Some differences can be seen when looking at how and by whom research software is developed. Out of necessity, we'll be generalizing here. For one, much research software is written by amateur developers. Best practices, programming technique and design patterns are usually not part of university curricula. Research software often has no users other than the individual or research group developing the package. Lastly, the average researcher has no stake in writing beautiful code, they have to publish beautiful results.
69
69
@@ -109,9 +109,9 @@ The second category is that of notebooks. A computational notebook consists of a
109
109
110
110
### True literate programming
111
111
112
-
The third category is that of literate programming systems. Some of these will have inevitable overlap with notebook interfaces, so a discussion on definition is in order. We consider a programming system to be literate if, from the ground up, it was designed to write a narrative story. The earliest systems by Knuth [@Knuth1984], called `WEB`, targeted \TeX\ and was meant to produce output optimized for print. Web used a system of references to deconstruct a program into narrative components. This system of references was a bit overcomplicated, which is why @Ramsey1994 came up with NoWeb. These systems would process the \TeX\ sources to extract a compilable source code, and as such were completely agnostic to the programming languages they were used with.
112
+
The third category is that of literate programming systems. Some of these will have inevitable overlap with notebook interfaces, so a discussion on definition is in order. We consider a programming system to be literate if, from the ground up, it was designed to write a narrative story. The earliest systems by Knuth [@Knuth1984], called `WEB`, targeted \TeX\ and was meant to produce output optimized for print. Web used a system of references to deconstruct a program into narrative components. This system of references was a bit overcomplicated, which is why Ramsey (1994) [@Ramsey1994] came up with NoWeb. These systems would process the \TeX\ sources to extract a compilable source code, and as such were completely agnostic to the programming languages they were used with.
113
113
114
-
A more modern adaptation of the same working principles can be found in Org-mode by @dominik. Org-mode is a very versatile markup format that can be used as a productivity tool, i.e. write small notes, to-do lists, or work journals. As such it is meant to be used from inside Emacs, where an interactive editor mode assists in organizing these notes. Over time org-mode has grown to do many tasks (in the spirit of Emacs itself), including literate programming. Org-mode has support for NoWeb references, tangling source codes and inline evaluation [@schulte2011active]. One of the limiting factors to the popularity of Org-mode has been its deep ties with the Emacs ecosystem.
114
+
A more modern adaptation of the same working principles can be found in Org-mode by Carsten Dominik [@dominik]. Org-mode is a very versatile markup format that can be used as a productivity tool, i.e. write small notes, to-do lists, or work journals. As such it is meant to be used from inside Emacs, where an interactive editor mode assists in organizing these notes. Over time org-mode has grown to do many tasks (in the spirit of Emacs itself), including literate programming. Org-mode has support for NoWeb references, tangling source codes and inline evaluation [@schulte2011active]. One of the limiting factors to the popularity of Org-mode has been its deep ties with the Emacs ecosystem.
115
115
116
116
Another popular solution for literate programming is RMarkdown [@RMarkdown]. RMarkdown is best worked with from RStudio, and uses Pandoc to convert Markdown documents to either print or web formats. With respect to literate programming techniques, it doesn't support NoWeb references, but it has more advanced weaving capabilities than either Jupyter or even Org-mode. Therefore, using RMarkdown it is possible to write complete self-reproducing papers. The downside is that the use of RMarkdown is limited to R and Python.
117
117
@@ -133,7 +133,7 @@ As with all classifications, there are always outliers. One such is `Pluto.jl`,
133
133
134
134
### Entangled
135
135
136
-
Entangled offers a method to do literate programming using Markdown as a markup language, generating static runnable or compilable source code in any chosen programming language. Thus far, Entangled may be considered a natural successor to the systems by @Knuth1984 and @Ramsey1994. The unique feature of Entangled among all other solutions discussed here is its capability to keep the literate Markdown source synchronized with the tangled source code in both directions.
136
+
Entangled offers a method to do literate programming using Markdown as a markup language, generating static runnable or compilable source code in any chosen programming language. Thus far, Entangled may be considered a natural successor to the systems by Knuth [@Knuth1984] and Ramsey [@Ramsey1994]. The unique feature of Entangled among all other solutions discussed here is its capability to keep the literate Markdown source synchronized with the tangled source code in both directions.
0 commit comments