el2markdown - Convert commentary section of elisp files to markdown

Author: Anders Lindgren
Version: 0.0.7
URL: https://github.com/Lindydancer/el2markdown

This package converts Commentary section in Emacs Lisp modules to text files in MarkDown format, a format supporting headings, code blocks, basic text styles, bullet lists etc.

The MarkDown is used by many web sites as an alternative to plain texts. For example, it is used by sites like StackOverflow and GitHub.

What is converted

Everything between the Commentary: and Code: markers are included in the generated text. In addition, the title and some metadata are also included.

How to write comments

The general rule of thumb is that the Emacs Lisp module should be written using plain text, as they always have been written.

However, some things are recognized. A single line ending with a colon is considered a heading. If this line is at the start of a comment block, it is considered a main (level 2) heading. Otherwise it is considered a (level 3) subheading. Note that the line precedes a bullet list or code, it will not be treated as a subheading.

Use Markdown formatting

It is possible to use markdown syntax in the text, like this, and this.

Conventions

The following conventions are used when converting elisp comments to MarkDown:

• Code blocks using either the Markdown convention by indenting the block with four extra spaces, or by starting a paragraph with a (.
• In elisp comments, a reference to code (backquote - quote), they will be converted to MarkDown style (backquote - backquote).
• In elisp comments, bullets in lists are typically separated by empty lines. In the converted text, the empty lines are removed, as required by MarkDown.

Example

;; This is a heading:
;;
;; Bla bla bla ...

;; This is another heading:
;;
;; This is a paragraph!
;;
;; A subheading:
;;
;; Another paragraph.
;;
;; This line is *not* as a subheading:
;;
;; * A bullet in a list
;;
;; * Another bullet.

Installation

Place this package somewhere in Emacs load-path and add the following lines to a suitable init file:

(autoload 'el2markdown-view-buffer  "el2markdown" nil t)
(autoload 'el2markdown-write-file   "el2markdown" nil t)
(autoload 'el2markdown-write-readme "el2markdown" nil t)

Usage

To generate the markdown representation of the current buffer to a temporary buffer, use:

M-x el2markdown-view-buffer RET

To write the markdown representation of the current buffer to a file, use:

M-x el2markdown-write-file RET name-of-file RET

In sites like GitHub, if a file named README.md exists in the root directory of an archive, it is displayed when viewing the archive. To generate a README.md file, in the same directory as the current buffer, use:

M-x el2markdown-write-readme RET

Post processing

To post-process the output, add a function to el2markdown-post-convert-hook. The functions in the hook should accept one argument, the output stream (typically the destination buffer). When the hook is run current buffer is the source buffer.

Batch mode

You can run el2markdown in batch mode. The function el2markdown-write-readme can be called directly using the -f option. The others can be accessed with the --eval form.

For example,

emacs -batch -l el2markdown.el my-file.el -f el2markdown-write-readme

Converted from el2markdown.el by el2markdown.