Homepage: https://github.com/cute-jumper/org2elcomment
Author: Junpeng Qiu
Updated:
Convert Org file to Elisp comments
_______________
ORG2ELCOMMENT
Junpeng Qiu
_______________
Table of Contents
_________________
1 Overview
2 Usage
.. 2.1 Command `org2elcomment'
.. 2.2 Command `org2elcomment-anywhere'
3 Customization
.. 3.1 Org Export Backend
.. 3.2 Exporter Function
Convert `org-mode' file to Elisp comments.
1 Overview
==========
This simple package is mainly used for Elisp package writers. After
you've written the `README.org' for your package, you can use
`org2elcomment' to convert the org file to Elisp comments in the
corresponding source code file.
2 Usage
=======
Make sure your source code file has `;;; Commentary:' and `;;; Code:'
lines. The generated comments will be put between these two lines.
If you use `auto-insert', it will take care of generating a standard
file header that contains these two lines in your source code.
2.1 Command `org2elcomment'
~~~~~~~~~~~~~~~~~~~~~~~~~~~
In your Org file, invoke `org2elcomment', select the source code file,
and done! Now take a look at your source code file, you can see your
Org file has been converted to the comments in your source code file.
2.2 Command `org2elcomment-anywhere'
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can invoke this command anywhere in Emacs. It requires two
parameters. You need to select the source code file as well as the
org file. After selecting the org file, you can optionally save the
org file location as the file-local variable in the source code file
so that you don't need to select the org file again for the same
source code file.
If you want to automate the process of converting the org to the
commentary section in Elisp file in your project, you can consider
using this command.
3 Customization
===============
3.1 Org Export Backend
~~~~~~~~~~~~~~~~~~~~~~
Behind the scenes, this package uses `org-export-as' function and the
default backend is `ascii'. You can change to whatever backend that
your org-mode export engine supports, such as `md' (for markdown):
,----
| (setq org2elcomment-backend 'md)
`----
3.2 Exporter Function
~~~~~~~~~~~~~~~~~~~~~
In fact, it is even possible to use your own export function instead
of the exporter of org-mode. Write a function which accepts a file
name of an org file and returns the string as the export result. Here
is how the default exporter that we use in this package looks like:
,----
| (defun org2elcomment-default-exporter (org-file)
| (with-temp-buffer
| (insert-file-contents org-file)
| (org-export-as org2elcomment-backend)))
`----
After defining your own export function, say, `my-exporter', change
the value of `org2elcomment-exporter':
,----
| (setq org2elcomment-exporter 'my-exporter)
`----