From: Robert Goldman <rpgoldman@sift.info>
To: Carsten Dominik <carsten.dominik@gmail.com>
Cc: Org Mode <emacs-orgmode@gnu.org>
Subject: Re: Re: OrgmodeOrg-export-generic and wikis...
Date: Fri, 21 May 2010 08:02:10 -0500 [thread overview]
Message-ID: <4BF68452.1070000@sift.info> (raw)
In-Reply-To: <8B022DDB-F211-42D1-842F-5C3B1DDEDF3E@gmail.com>
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
>>>>>>>>> <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
>
>
>
prev parent reply other threads:[~2010-05-21 13:02 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-04-28 19:38 Org-export-generic and wikis Robert Goldman
2010-04-29 13:57 ` OrgmodeOrg-export-generic " Wes Hardaker
2010-04-29 14:14 ` Carsten Dominik
2010-04-29 15:18 ` Robert Goldman
2010-05-14 7:16 ` Carsten Dominik
2010-05-21 13:02 ` Robert Goldman [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=4BF68452.1070000@sift.info \
--to=rpgoldman@sift.info \
--cc=carsten.dominik@gmail.com \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).