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

[Robert Goldman]

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