From mboxrd@z Thu Jan 1 00:00:00 1970 From: Robert Goldman Subject: Re: Re: OrgmodeOrg-export-generic and wikis... Date: Fri, 21 May 2010 08:02:10 -0500 Message-ID: <4BF68452.1070000@sift.info> References: <4BD88EC7.5070507@sift.info> <4BD9A330.6060501@sift.info> <8B022DDB-F211-42D1-842F-5C3B1DDEDF3E@gmail.com> Reply-To: rpgoldman@sift.info Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Return-path: Received: from [140.186.70.92] (port=55872 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OFRri-00066h-Ea for emacs-orgmode@gnu.org; Fri, 21 May 2010 09:02:15 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OFRrf-0006tJ-Pe for emacs-orgmode@gnu.org; Fri, 21 May 2010 09:02:14 -0400 Received: from mpls.sift.info ([75.146.46.193]:33960) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OFRrf-0006tC-I0 for emacs-orgmode@gnu.org; Fri, 21 May 2010 09:02:11 -0400 In-Reply-To: <8B022DDB-F211-42D1-842F-5C3B1DDEDF3E@gmail.com> 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: Carsten Dominik Cc: Org Mode On 5/14/10 May 14 -2:16 AM, Carsten Dominik wrote: > 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. I have sent Wes a couple of proposed patches for inspection. We should probably wait until he's had a chance to look at them. They include the introduction of a declaration macro for the keywords that are used to configure a generic exporter. Also, I should probably get the fontification fully done before pushing. Question: do you ever have a shared branch? If it would be more convenient for you and Wes, I suppose I could be pushing my patches onto a branch on your repo, instead of emailing patches. Whatever works best for you two. Cheers, r > > - 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 > > >