From: Paul Sexton <psexton@xnet.co.nz>
To: emacs-orgmode@gnu.org
Subject: Programmers, use org to write your doc strings...
Date: Wed, 3 Mar 2010 00:03:48 +0000 (UTC) [thread overview]
Message-ID: <loom.20100303T002145-17@post.gmane.org> (raw)
Hi
I think org is a good platform for writing documentation for
source code. The "babel" module is one approach, but it presumes
that org is the dominant major mode, and the actual source code
is divided into snippets here and there.
I wanted to look into another way of doing it: the source code's
mode is dominant, with snippets of org mode here and there. Babel
in reverse if you will.
I have used mmm-mode, which is part of nXhtml mode, which you
can download at:
http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl
I have managed to get it working for common lisp. Users of other
programming languages should easily be able to achieve the same
effect by modifying the elisp code below.
In a lisp buffer, documentation strings use org mode as their
major mode, while the rest of the file uses lisp-mode. All the
fontification works, as does formatting of bulleted lists
etc. Hyperlink overlays don't work (you see [[the whole][link]]
rather than the short form), but the links themselves work.
We define a docstring as:
1. A string which emacs has fontified using the font lock
docstring face
2. A string that comes after '(:documentation '
3. A string whose first three characters are ###
MMM-mode sometimes seems to need a bit of a poke to recognise new
docstrings. If it's not recognising things that it should, press
ctrl-` to refresh it.
My motivation is that I have written a "doxygen"-like program for
common lisp, called CLOD, whose output is an org mode file. You
can use org mode markup in common lisp docstrings, and the markup
will be understood when the docstrings are read by CLOD. Now, I
can edit those docstrings within the lisp source file and get all
org's fontification, at formatting of bulleted lists, hyperlinks,
etc. All without leaving emacs.
Paul
---------contents of .emacs follows---------------------------
(add-to-list 'load-path "/path/to/mmm-mode"))
(require 'mmm-auto)
(setq mmm-global-mode 'maybe)
(mmm-add-mode-ext-class 'lisp-mode nil 'org-submode)
(mmm-add-mode-ext-class 'slime-mode nil 'org-submode)
;; The above, using major mode symbols, didn't seem to work for
;; me so I also added these line (regexp uses same format as
;; major-mode-alist):
(mmm-add-mode-ext-class nil "\\.lisp$" 'org-submode)
(mmm-add-mode-ext-class nil "\\.asd$" 'org-submode)
(setq mmm-submode-decoration-level 2)
;; This prevents transient loss of fontification on first
;; calling `mmm-ify-by-class'
(defadvice mmm-ify-by-class (after refontify-after-mmm
activate compile)
(font-lock-fontify-buffer))
;; bind control-backquote to "refresh" MMM-mode in current buffer.
(global-set-key [?\C-`] (lambda () (interactive)
(mmm-ify-by-class 'org-submode)))
;; And the definition of 'org-submode
(mmm-add-group 'org-submode
'((org-submode1
:submode org-mode
;; This face supplies a background colour for org
;; parts of the buffer. Customizable.
:face mmm-declaration-submode-face
:front "\""
:back "[^\\]\""
:back-offset 1
:front-verify check-docstring-match
:end-not-begin t)
(org-submode-2
:submode org-mode
:face mmm-declaration-submode-face
;; Match '(:documentation "...")' docstrings
:front "(:documentation[\t\n ]+\""
:back "[^\\]\""
:back-offset 1
:end-not-begin t)))
(defun face-at (pos)
(save-excursion
(goto-char pos)
(face-at-point)))
(defun check-docstring-match ()
(interactive)
(let ((beg (match-beginning 0))
(end (match-end 0)))
(cond
;; Docstring if emacs has fontified it in 'docstring' face
((eql (face-at end) 'font-lock-doc-face)
t)
;; Docstring if the first three characters after the opening
;; quote are "###"
((string= (buffer-substring end (+ 3 end)) "###")
t)
(t
nil))))
next reply other threads:[~2010-03-03 0:04 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-03-03 0:03 Paul Sexton [this message]
2010-03-03 0:19 ` Programmers, use org to write your doc strings Samuel Wales
2010-03-03 12:16 ` Carsten Dominik
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=loom.20100303T002145-17@post.gmane.org \
--to=psexton@xnet.co.nz \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).