# Markdown Literary programming that don't break the syntax of any programming language [1]
## Comment Area Markup Method
Literary Programming, Programming was the first, Literary was the second.
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.
Just add a line comment character of the programming language before each line of Markdown.
In the comments of code, you can draw flowcharts,tasklist,
display data visualizations, etc.
The method is to add extension instructions
in any programming language comment area:
- markdown
- manual eval code, live eval code, print result,
display data visualization and other directives
When previewing or converting a format,
you only need to simply preprocess:
delete line comment characters with regular expressions,
example: `sed 's/^;//' x.clj`
Note:
- line comment character of Clojure(Lisp) is `;`
- line comment characters of the current file type
can be obtained from the editor's API.
when we edit the code, we can preview the effect in real time. Editing literary code has a live preview panel like most markdown editors.
## Advantages
- fast, live, simple, no interference.
- It don't break the syntax of any programming language, you can compile directly. comment area markup method can be applied to any programming language and any markup
(including Org,rst, asciidoc, etc.), which is the greatest advantage.
- you only need a single line code to delete line comment characters using regular expressions, 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.
- When writing (reading or refactoring) code files, It can modify and live preview directly in the editor without exporting or any preprocessing.
- Reliable. Maximum code accuracy is guaranteed, and markup language errors do not affect the code.
- It hasn't interfere anyone to read the code.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 gray comment area can reduce the amount of information in the source code file, conducive to reading code.
## Disadvantages of traditional literary programming
- because traditional literary programming users
are mainly technical writers, speakers,
technical document Maintainers,
Style is the document priority, greatly increase
the amount of information in the code,
interfere with the code reading,
especially for non-literary programming programmers
are unfriendly, or even unreadable,
so there are very few applications in the field of
programming.
- not universal, specific programming languages and markup languages.
- Requires a complex pre-compiler.
- Complex to use and high learning costs.
- Not intuitive.
Therefore, the method described in this paper,
in addition to the document-first genre of
traditional literary programming,
has innovated a new genre ---- code-first genre,
so that literary programming in the field of
programming Widely used as possible.
In my preferred IDE (IntelliJ) you can enable rendered documentation view which will take the source code comments and render them through some kind of limited HTML renderer.
I much prefer that to switching to Markdown. Markdown is great for plain text but it's not great for this type of content imo.
To date, I haven't seen a flavor of Markdown that has a comment feature. I use it extensively to hide all my notes that don't have a place in the final exported document people will read.
Also simpler mentally when writing comments: this handful of markup is supported, period: just write a plain text comment, to show as plain text, no fancy formatting encouraged.
Of course, you can type your comments in Markdown today; they just won't be rendered as such. :)
Anyway, the audience here would probably make good use of such a feature, and comments would benefit from all the nice formatting options that people are already familiar with from Stack Overflow, GitHub, and other places on the web.
I'm not sure how HN would transition to support Markdown rendering of comments. Perhaps some problem with the transition is the only reason this hasn't been done already.
In any case, wouldn't this be a solid feature add for the site?
comment area markup method can be applied to any programming language and any markup (including Org,rst, asciidoc, etc.), which is the greatest advantage. :-)
I dislike this style. First off, it’s just a block comment. Secondly, although raw markdown isn’t terrible to read, it makes it slightly hard to read the actual code as text, say in emacs. But the worst thing is that folks who code like this tend away from inline comments, which I find usually more useful in complex code.
reply