Re: [Orgmode] Re: OrgmodeOrg-export-generic and wikis...

[Robert Goldman]

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
>>>>>>>>> <address@hidden> 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
> 
> 
>