From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carsten Dominik Subject: Re: Programmers, use org to write your doc strings... Date: Wed, 3 Mar 2010 13:16:01 +0100 Message-ID: <9DD17A0B-D91D-4A4A-B2D3-C7E41C511A68@gmail.com> References: Mime-Version: 1.0 (Apple Message framework v936) Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes Content-Transfer-Encoding: 7bit Return-path: Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1NmnUz-0005uA-45 for emacs-orgmode@gnu.org; Wed, 03 Mar 2010 07:16:21 -0500 Received: from [140.186.70.92] (port=54524 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NmnUx-0005su-RG for emacs-orgmode@gnu.org; Wed, 03 Mar 2010 07:16:20 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1NmnUw-00039C-Ue for emacs-orgmode@gnu.org; Wed, 03 Mar 2010 07:16:19 -0500 Received: from mail-ew0-f222.google.com ([209.85.219.222]:39339) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1NmnUw-000396-Mi for emacs-orgmode@gnu.org; Wed, 03 Mar 2010 07:16:18 -0500 Received: by ewy22 with SMTP id 22so997674ewy.26 for ; Wed, 03 Mar 2010 04:16:17 -0800 (PST) In-Reply-To: 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: Paul Sexton Cc: emacs-orgmode@gnu.org Hi Paul, this looks useful - maybe you want to add this code to org-hacks.php on Worg? Best wishes - Carsten On Mar 3, 2010, at 1:03 AM, Paul Sexton wrote: > 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)))) > > > > > > > _______________________________________________ > Emacs-orgmode mailing list > Please use `Reply All' to send replies to the list. > Emacs-orgmode@gnu.org > http://lists.gnu.org/mailman/listinfo/emacs-orgmode - Carsten