[idea] Markdown Literary Programming that don't break the syntax of any programming language

linpengcheng · February 17, 2019, 5:38am

Markdown Literary programming for compatible codes. Just add a custom line comment character before each line of Markdown.

In the comments of code, you can draw flowcharts, tasklist, display data visualizations image, etc.

When previewing or converting a format, you only need to simply preprocess: replace the \r\n\; with \r\n

example:

;# Markdown literary programming
;## example01:
;```clojure
(defn f [[evens odds total amax amin] x]
  (let [[evens odds] (cond 
                       (even? x) [(inc evens ) odds]
                       (odd? x)  [evens (inc odds)]
                       :else     [evens odds])
        total (+ total x)
        amax  (max amax x)
        amin  (min amin x)]   
     [evens odds total amax amin]))
;;The comment of the code requires at least two line comment characters
(reduce f [0 0 0 ##-Inf ##Inf] [5 6 8 -3 -9 11 156 6 7])
;```
;return`[4 5 187 156 -9]`

Screenshot

mv3

avichalp · February 17, 2019, 3:39pm

Interesting. I was thinking about something similar. I thought we can extract doc-strings and function source from any namespace and put them together in a string in MD format. Export in to a markdown file to read at leisure.

linpengcheng · February 17, 2019, 3:54pm

I mean, when we edit the code, we can preview the effect in real time. Editing literary code has a live preview like most markdown editors.

The editor has a Live Preview panel to do the following work:

Get the current text
replace the \r\n\; with \r\n (note: line breaks and line comment characters of the current file can be obtained from the editor’s API.)
live Preview markdown string

daslu · February 17, 2019, 6:50pm

Interesting!

By the way, this is similar to Gorilla Repl’s format.

linpengcheng · February 18, 2019, 12:33am

Its advantages:

Do not break the syntax of any programming language, you can compile directly.
you only need a single line of regular replacement preprocessing, then you can use any Markdown parse or converter.
Support any code editor that supports Markdwon Live preview, allowing the source code of any programming language to become rich text in real time. In the code’s comment area, You can use the markdown to draw flowcharts, tables, task lists, and display images on the live preview panel, enhance the readability of your code.
If you extend the Markdwon tag, you can implement the eval code, print result, display data visualization and other instruction tags, to achieve live programming, live test.
Easily export directly to PDF or HTML.

jiyinyiyong · February 18, 2019, 3:36am

Have you looked into Literate CoffeeScript https://coffeescript.org/#literate

also the doc it generated https://coffeescript.org/annotated-source/scope.html

linpengcheng · February 18, 2019, 4:50am

I have not looked into Literate CoffeeScript.

The most important thing is that my comment area markup method can be applied to any programming language and any markup (including Org,rst, asciidoc, etc.), which is the greatest advantage.

if you break the programming language syntax, like org, this is the biggest drawback.

generateme · February 18, 2019, 7:46pm

Take a look at marginalia https://github.com/gdeer81/marginalia

linpengcheng · February 19, 2019, 1:44am

Your project is good, but the main purpose of the Code comment area markup method is to live Preview directly in the Code Editor Preview panel without exporting or any preprocessing.

I think:

Literary Programming, Programming was the first, Literary was the second.
The entire file is compliant with the programming language syntax and can be compiled directly.
When writing (reading or refactoring) code files, I can modify and live preview directly in the editor without exporting or any preprocessing.
Do not interfere with people who do not understand the markup language to read the code.
Reliable. Maximum code accuracy is guaranteed, and markup language errors do not affect the code.

daslu · February 19, 2019, 7:23am

Interesting!

It is worth looking into the current discussion at Clojurians Zulip, with some nice (similar) ideas by @didibus:

link

alanmarazzi · February 19, 2019, 9:18am

There’s already something similar for Clojure: https://github.com/eccentric-j/book-report

geokon-gh · February 19, 2019, 9:26am

You could probably set this up with inotify and marginalia - so that each time you save your file it would regenerate the HTML and then it’d autorefresh in your browser window?

I’ve found running marginalia slow, so you’d need to find a way to speed things up by maybe having it run as some daemon

I do really like it’s side-by-side layout though and I use it in shorter programs where orgmode is overkill. And I do feel the layout is better than the traditional literate/org-mode vertical layout.

That all being said - I’ve never used live-preview while writing literate programs. I find that with the right highlighting it’s basically just as nice to stick to the raw text-form. Some emacs themes seem to extend org-mode’s highlighting so that it’s all visually easier to parse

So I feel the most pragmatic solution would just be a syntax highlighting layer on top of the existing Clojure one that would highlight the comment areas appropriately (which would be still written in a markdown/marginalia style). Something so it’s not all just light grey, but similar to the way text is highlighted in org, and then visually separate the code section with like a separate background or something to that effect. I think that’d get you 80% to where you want.

But the way things are right now, it’s a bit of an eyesore writing big grey code comment blocks

linpengcheng · February 19, 2019, 9:36am

code comment area markup method can be in the editor preview panel live Preview, it’s fast.

Markdown is simple, so if it doesn’t have syntax highlighting, it doesn’t have much effect on writing and reading.

And having a gray comment area doesn’t affect reading code, especially for people who don’t understand the markup language.

Strict distinction between markdown and code, and markdown Gray, can reduce the amount of information in the source code file, conducive to reading code.

@geokon-gn Your method is document first, used to generate the document.

code comment area markup method is code first. used as a rich text code comments and Live Programming.

two methods apply different scenarios

linpengcheng · February 19, 2019, 2:18pm

Marp uses the comment area to extend the Markdown directive to achieve “Markdown presentation Writer”, which is a good reference mechanism.

https://github.com/yhatt/marp/

https://yhatt.github.io/marp/

Marp markdown Comment Area extended directive:

slide directive

Clojure Comment Area extended directive:

markdown
manual eval code, live eval code, print result, display data visualization and other directives

0atman · February 21, 2019, 8:07am

I love it! I adore literate programming, and ideas on this space are more of what we need. I really dig Marginalia, too. In my research, my favourite tool for readable documentation.

I had a go at my own LP tool a while back http://blaze.oat.sh/
Similar to Linpeng’s method, this just requires some frontmatter, for Blaze, its a shebang.

There are two schools of thought here: document-first (blaze), or code-first (Linpeng’s).

A small video I made talking about blaze, literate programming, and testing: https://youtu.be/eTQmlSL4L6c

What I’d love to see is first-class literate support in Clojure, like the aforementioned coffeescript, and like haskell.
Perhaps a lein preprocessor plugin?

Humans first, computers second!

jackrusher · February 23, 2019, 2:04am

This is very similar to the source code format we use under the covers for http://maria.cloud.

linpengcheng · February 24, 2019, 5:18am

Because the article is long and inconvenient for typesetting, the complete presentation, notepad++ solution and patch see the links below:

Markdown Literary programming that don’t break the syntax of any programming language

linpengcheng · February 28, 2019, 1:44am

There is a markdown extension tag project that can execute tagged r (python, Julia, Rust) code.

Live code in Pandoc Markdown

https://github.com/gpoore/codebraid

generateme · March 1, 2019, 10:44am

Just a quick PoC based on Marginalia parser.

gist.github.com

https://gist.github.com/genmeblog/14a03bf7ee67f3435376e482e3981759

converter.md



# Convert source code to Markdown using Marginalia parser

```clojure
(ns mrgtst.core
  (:require [marginalia.parser :as p]
            [clojure.string :as str]))
```

This file has been truncated. show original

core.clj

;; # Convert source code to Markdown using Marginalia parser
;;
(ns mrgtst.core
  (:require [marginalia.parser :as p]
            [clojure.string :as str]))

(defn- code-block
  "Create code block from given string `s`"
  [s]
  (str "\n```clojure\n" s "\n```\n\n"))

This file has been truncated. show original

linpengcheng · March 5, 2019, 2:09pm

PythonScipt Solutions for Notepad++ Markdown Literary Programming

This PythonScript code is also a Markdown Literary Programming example.