2 ms·
This looks great! Free software under the AGPL, too! For my own notes, I've mostly been using Markdown, which doesn't have fenced code blocks, but I've been t
by kragen 4y ago
This looks great! Free software under the AGPL, too!
For my own notes, I've mostly been using Markdown, which doesn't have fenced code blocks, but I've been thinking I might upgrade to a different language like CommonMark or GitLab-Flavored Markdown that does support them. One of the main reasons is the possibility of embedding non-text things in my notes; for example, the other day I was messing around with exact pole-zero cancellation in DSP in https://nbviewer.org/url/canonical.org/~kragen/sw/dev3/pole-zero-cancellation.ipynb https://nbviewer.org/url/canonical.org/~kragen/sw/dev3/pole-..., which involved a lot of TeX equations and data plots of algorithmically generated output. Jupyter notebooks can do those things, but they have a number of extremely serious drawbacks for this sort of thing, such as irreproducibility, aggressively backwards-incompatible file formats, lack of interactivity (despite ipywidgets), unacceptably large "source code" file size, and spurious merge conflicts in Git.
An interesting approach to solving this problem is Mermaid (https://docs.gitlab.com/ee/user/markdown.html#diagrams-and-flowcharts https://docs.gitlab.com/ee/user/markdown.html#diagrams-and-f...), which lets you include a ```mermaid fenced code block in your Markdown source and replaces it with a rendered image of a boxes-and-arrows diagram in the HTML output. This is sort of backwards-compatible with regular GLFM because things that don't support Mermaid just show the diagram's source code. Mermaid's "flowchart" diagram type is vaguely similar to Graphviz, but I think Graphviz has better syntax and nicer output, so I'd rather use Graphviz for this; Mermaid also has Gantt charts, UML diagrams, sequence diagrams, and entity-relationship diagrams.
GitLab also supports language-tagged fenced code blocks for "math" (KaTeX's subset of LaTeX), "plantuml" (disabled by default, does UML diagrams), and Kroki (also disabled by default, supports Graphviz, Ditaa (warning, domain stolen by SEOs) for flowcharts, Wavedrom for digital timing diagrams, Vega-Lite for data plotting with interactive exploration from JSON, Svgbob for a fairly comprehensive set of ASCII-art line drawings, Burntsushi's Erd for entity-relationship diagrams, bytefield-svg, Pikchr for PIC-like things, several different ASCII-to-UML things, and another dozen or so other similar things).
Pikchr, from the Fossil/SQLite folks, is also designed for embedding in GFML and similar Markdown-derived languages, even without Kroki.
But most of these are just data formats, rather than rich data models or executable code like I'd need for the DSP algorithms I mentioned above. The closest thing I've found for that is Yihui Xie's R Notebooks: https://bookdown.org/yihui/rmarkdown/notebook.html https://bookdown.org/yihui/rmarkdown/notebook.html where you can put fenced R code blocks into your Markdown and display the output inline both in the RStudio IDE and in the final rendered document. This still has Jupyter's problem with reproducibility, but solves the problems with massive source files, file-format backwards compatibility, and spurious merge conflicts.
However, R Notebooks require you to write your code in R, which isn't ideal for all purposes, and as far as I know the rendered results don't have a way to do Vega-style or ObservableHQ-style interactive exploration. Also, pretty often I find it easier to sketch a diagram with a pencil than to write code to produce it.
And, for things like analog circuit schematics or 3-D models, while a compact textual representation is achievable, it often isn't the ideal user interface for editing. Mermaid Live, OpenSCAD, and dot -Tx11 filename.gv are three approaches where the text-to-picture flow is one-way, and while they're pretty great, you still spend a fair bit of time hunting through source code for the thing you want to edit and trying to diagnose syntax errors.
So I'd like to have a note-taking system that supports Git and Commonmark, reproducibility so that I don't need to check in giant binary files representing render outputs, plug-in visualizers for different kinds of quasi-textual content, and plug-in editors for editing things like 3-D models, circuit schematics, and 2-D sketches. And I'd like to be able to do things like run a SPICE simulation of a circuit schematic, a FEM simulation of a 3-D model, or a numerical integration of a Modelica model.
Is there anything like that out there? What are the alternative approaches to this kind of algorithmic exploration such as ObservableHQ?
The DSP notebook I mentioned above also includes an input audio sample and several processed versions of it, which you can't hear in the online Jupyter notebook viewer but you can hear if you run it locally. The input audio sample would pretty much have to be an external file, same as a photo, but ideally the processed versions could be recomputed reproducibly rather than stored in Git and copied around all over the net.