Re: Re: OrgmodeOrg-export-generic and wikis...

[Carsten Dominik <carsten.dominik@gmail.com>]

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
>>>>>>>> <rpgoldman@sift.info> 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