From mboxrd@z Thu Jan 1 00:00:00 1970 From: Paul Sexton Subject: Programmers, use org to write your doc strings... Date: Wed, 3 Mar 2010 00:03:48 +0000 (UTC) Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Return-path: Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Nmc4S-0004rc-UP for emacs-orgmode@gnu.org; Tue, 02 Mar 2010 19:04:12 -0500 Received: from [140.186.70.92] (port=41122 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Nmc4P-0004rU-Cc for emacs-orgmode@gnu.org; Tue, 02 Mar 2010 19:04:11 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1Nmc4L-0003TI-V5 for emacs-orgmode@gnu.org; Tue, 02 Mar 2010 19:04:09 -0500 Received: from lo.gmane.org ([80.91.229.12]:35027) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Nmc4L-0003T3-Fx for emacs-orgmode@gnu.org; Tue, 02 Mar 2010 19:04:05 -0500 Received: from list by lo.gmane.org with local (Exim 4.69) (envelope-from ) id 1Nmc4I-0006Yr-Pg for emacs-orgmode@gnu.org; Wed, 03 Mar 2010 01:04:03 +0100 Received: from rp.young.med.auckland.ac.nz ([130.216.140.20]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Wed, 03 Mar 2010 01:04:02 +0100 Received: from psexton by rp.young.med.auckland.ac.nz with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Wed, 03 Mar 2010 01:04:02 +0100 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org 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))))