From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carsten Dominik Subject: Re: Re: OrgmodeOrg-export-generic and wikis... Date: Fri, 14 May 2010 09:16:50 +0200 Message-ID: <8B022DDB-F211-42D1-842F-5C3B1DDEDF3E@gmail.com> References: <4BD88EC7.5070507@sift.info> <4BD9A330.6060501@sift.info> 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 [140.186.70.92] (port=40105 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OCp8o-0001J9-TC for emacs-orgmode@gnu.org; Fri, 14 May 2010 03:17:05 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OCp8i-0000A2-E1 for emacs-orgmode@gnu.org; Fri, 14 May 2010 03:17:02 -0400 Received: from mail-ww0-f41.google.com ([74.125.82.41]:44455) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OCp8h-00009t-S7 for emacs-orgmode@gnu.org; Fri, 14 May 2010 03:16:56 -0400 Received: by wwa36 with SMTP id 36so269291wwa.0 for ; Fri, 14 May 2010 00:16:54 -0700 (PDT) In-Reply-To: <4BD9A330.6060501@sift.info> 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: rpgoldman@sift.info Cc: Org Mode Hi Robert, Wes, I am not sure if there is any action should be taking here? I have no problems bundling some documentation with the distribution - let me just know what you want and send me what I should distribute. - Carsten On Apr 29, 2010, at 5:18 PM, Robert Goldman wrote: > On 4/29/10 Apr 29 -9:14 AM, Carsten Dominik wrote: >> >> On Apr 29, 2010, at 3:57 PM, Wes Hardaker wrote: >> >>>>>>>> On Wed, 28 Apr 2010 14:38:47 -0500, Robert Goldman >>>>>>>> said: >>> >>> RG> 1. Would it be reasonable to move the documentation for >>> RG> org-export-generic into the contrib/ directory of org-mode? It >>> RG> seems ... suboptimal to have this package be maintained in the >>> org >>> RG> git repo, but its documentation in the worg git repo. At >>> least from >>> RG> my PoV this raises the bar for keeping the documentation up-to- >>> date >>> RG> and synchronized to a pretty high level. >>> >>> I'll let Carsten answer questions like that ;-) >> >> The reason for this is the following. >> >> Many of the contributed packages where written by people who were >> active >> in Org-mode for a while and then less so. Many of these package >> had no >> documentation at all. So I started a page on WOrg where this >> documentation can be added and edited by other users, with quite >> some success - now most package do have documentation. >> >> Keeping documentation for a contributed package the the org-repo >> would >> be OK, but there would be no mechanism to automatically put the >> latest >> version up on on the web. >> >> Changing this would require a volunteer who commits to keep the >> documentation >> of contributed packages in a consistent and web-publishable way in >> the >> contrib directory. > > Here's the particular problem for org-export-generic --- maybe > there's a > solution: > > org-export-generic is primarily data-driven. To specify an export > technique, you populate a very big data structure using a macro with > what look like common-lisp keywords. Here's an example: > > > > (org-set-generic-type > "tikiwiki" > '(:file-suffix ".txt" > :key-binding ?U > > ;; lifted from wikipedia exporter > :header-prefix "" > :header-suffix "" > > :title-format "-= %s =-\n" > > :date-export nil > > :toc-export nil > > :body-header-section-numbers nil > :body-section-prefix "\n" > > :body-section-header-prefix ("! " "!! " "!!! " "!!!! " > "!!!!! " "!!!!!! " "!!!!!!! ") > :body-section-header-suffix (" \n" " \n" " \n" > " \n" " \n" " \n") > > > :body-line-export-preformated t ;; yes/no/maybe??? > :body-line-format "%s " > :body-line-wrap nil > > :body-line-fixed-format " %s\n" > > :body-list-format "* %s\n" > :body-number-list-format "# %s\n" > ;; :body-list-prefix "LISTSTART" > ;; :body-list-suffix "LISTEND" > :blockquote-start "\n^\n" > :blockquote-end "^\n\n" > :body-newline-paragraph t > )) > > The problem is that this is VERY difficult to document as the set of > keywords expands (e.g., I add :body-newline-paragraph, :blockquote- > start > and :blockquote-end). These aren't arguments, so they can't get > documented in the code in a docstring. org-set-generic-type is a > function, not a mode, so there's no docstring for the mode to hold the > documentation. > > This is already not working, AFAICT, the worg docs don't seem to be > complete or accurate. > > I'm pretty convinced from general code and document-writing practice > that the best solution would be one that puts the documentation as > close > to the code as possible. > > If this were common-lisp, I would add a new method to the > DOCUMENTATION > generic function, so that one could say > > (documentation :body-newline-paragraph :org-export-keyword) > > Then we could add a declaration macro, and put the docstring there: > > (def-generic-export-keyword :body-newline-paragraph > :boolean > "Should newlines ONLY be used as paragraph breaks. If > the associated value is true, then org-export-generic will > flow contiguous paragraphs into one long line, adding newlines > only where there is a blank line. Should be coupled with a > value for :body-line-format that does NOT contain a newline > character, e.g., \"%s \"") > > I suppose we could add something like this, and possibly even > write a script that would blat the docstring into something that > Worg could display. > > Any thoughts? > > Best, > > r > > - Carsten