-- encoding:utf-8 Mode: POLY-ORG; -- ---

#+Startup: noindent #+PROPERTY: header-args :results silent :eval no-export :comments org #+OPTIONS: num:nil toc:nil todo:nil tasks:nil tags:nil #+OPTIONS: skip:nil author:nil email:nil creator:nil timestamp:t #+INFOJS_OPT: view:nil toc:nil ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js [[https://clojars.org/literate-clojure][file:https://img.shields.io/clojars/v/literate-clojure.svg]] [[https://travis-ci.com/jingtaozf/literate-clojure][file:https://travis-ci.com/jingtaozf/literate-clojure.svg?branch=master]] [[https://github.com/jingtaozf/literate-clojure/actions][file:https://github.com/jingtaozf/literate-clojure/workflows/Clojure%20CI/badge.svg]]

• Table of Contents :TOC:

• [[#introduction][Introduction]]
• [[#tutorial][Tutorial]]
  • [[#install-polymode-in-emacs][install polymode in emacs]]
  • [[#how-to-insert-code-block-quickly][how to insert code block quickly]]
  • [[#add-dependence-in-projectclj][Add dependence in project.clj]]
  • [[#load-org-file][Load org file]]
  • [[#the-special-requirement-for-org-files][The special requirement for org files]]
  • [[#a-new-code-block-header-argument-load][a new code block header argument load]]
• [[#license][License]]

• Introduction
  This is a clojure library designed to extend the clojure syntax
  so it can load org file as source file directly.

The implementation details of [[https://github.com/jingtaozf/literate-clojure][literate-clojure]] is in file [[./src/literate_clojure/core.org][core.org]] ([[./src/literate_clojure/core.pdf][pdf version]]).

This library is provided to make litrate programming more happy in clojure,without pain of tangling code from org files.

This library contains the following files:

• [[./src/literate_clojure/core.org]] \
  The implementation and documentation and literate clojure reader.
• [[./src/literate_clojure/core.clj]] \
  The tangled codes of literate clojure reader, generated from [[./src/literate_clojure/core.clj]].
• [[./src/literate_clojure/core.pdf]] \
  The weaved documentation, generated from [[./src/literate_clojure/core.clj]] by org mode's [[https://orgmode.org/manual/Triggering-publication.html#Triggering-publication][publish feature]].
• [[test/literate_clojure/core_test.org]] \
  The testcase of [[https://github.com/jingtaozf/literate-clojure][literate-clojure]].
• [[test/literate_clojure/core_test.clj]] \
  The bootstrap file of test cases.
• [[./README.org]] \
  The usage and introduction of [[https://github.com/jingtaozf/literate-clojure][literate-clojure]].
• [[./project.clj]] \
  the lein project file of [[https://github.com/jingtaozf/literate-clojure][literate-clojure]].
• [[./demo/project.clj]] \
  the lein project file of a demo of how to use [[https://github.com/jingtaozf/literate-clojure][literate-clojure]].
• [[./demo/src/demo/literate_core.clj]] \
  The demo documentation and codes.
• [[./demo/src/demo/core.clj]] \
  the bootstrap file to load [[./demo/src/demo/literate_core.clj]].
• [[./.travis.yml]] \
  The config file used by Web service [[https://travis-ci.com/jingtaozf/literate-lisp][travis ci]] to test this library.

• Tutorial
  ** install polymode in emacs
  It's better to edit the org file with [[https://polymode.github.io/][polymode]],which will make code block use its native file mode.
  The following elisp scripts in .emacs will install it.
  #+BEGIN_SRC elisp
  (use-package poly-org
  :ensure t)
  #+END_SRC
  Usually I will add the following line as the first line of an clojure source file (*.clj or *.cljs)
  #+BEGIN_SRC elisp

-- encoding:utf-8 Mode: POLY-ORG; -- ---

#+END_SRC But GitHub will not render such file in org mode, to fix this issue, I will add the following line as the first line instead. #+BEGIN_SRC elisp

-- encoding:utf-8 Mode: ORG; -- ---

#+END_SRC And in my Emacs configuration file, I will add a hook to enable [[https://polymode.github.io/][polymode]] for such file: #+BEGIN_SRC elisp (defun enable-poly-org-mode () (when (and buffer-file-name (not (string= "org" (downcase (file-name-extension buffer-file-name))))) (poly-org-mode 1))) (add-hook 'org-mode-hook 'enable-poly-org-mode) #+END_SRC So Github can render such source file as org mode correctly. ** how to insert code block quickly Please have a look of the section [[https://github.com/jingtaozf/literate-elisp/blob/master/literate-elisp.org#how-to-insert-code-block-in-org-file][How to insert code block in org file]] in library [[https://github.com/jingtaozf/literate-elisp][literate-elisp]]. ** Add dependence in project.clj To use this library, please add dependence in your [[./demo/project.clj][project.clj]]: #+BEGIN_SRC clojure :dependencies [[literate-clojure "0.1.1"]] #+END_SRC ** Load org file Then in one of your [[./demo/src/demo/core.clj][source file]],add the following codes to install the org syntax for clojure reader: #+BEGIN_SRC clojure (require 'literate-clojure.core) (literate-clojure.core/install-org-dispatcher) (load-file "src/demo/core.org") #+END_SRC Now you can use [[./demo/src/demo/literate_core.clj][literate_core.clj]] to write your documentation and source codes together, and any codes in [[./demo/src/demo/core.org][core.org]] will be loaded automatically. ** The special requirement for org files The org files must start with a sharp and a space, for example I usually add the following line to the beginning of an org file: #+BEGIN_SRC org

-- encoding:utf-8 Mode: POLY-ORG; -- ---

#+END_SRC It will use Emacs library [[https://github.com/polymode/poly-org][poly-org-mode]] which is a lightweight library to support multiple major mode in one file, so you can edit clojure code natively in an org file. ** a new code block header argument load Please have a look of the section [[./src/literate_clojure/core.org#handle-org-syntax][handle org syntax]] in [[./src/literate_clojure/core.org][./src/literate_clojure/core.org]].

• License

Copyright © 2018 Jingtao Xu

This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at http://www.eclipse.org/legal/epl-2.0.

This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version, with the GNU Classpath Exception which is available at https://www.gnu.org/software/classpath/license.html.