From: Carsten Dominik <carsten.dominik@gmail.com>
To: rpgoldman@sift.info
Cc: Org Mode <emacs-orgmode@gnu.org>
Subject: Re: Re: OrgmodeOrg-export-generic and wikis...
Date: Fri, 14 May 2010 09:16:50 +0200 [thread overview]
Message-ID: <8B022DDB-F211-42D1-842F-5C3B1DDEDF3E@gmail.com> (raw)
In-Reply-To: <4BD9A330.6060501@sift.info>
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
next prev parent reply other threads:[~2010-05-14 7:17 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 [this message]
2010-05-21 13:02 ` Robert Goldman
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=8B022DDB-F211-42D1-842F-5C3B1DDEDF3E@gmail.com \
--to=carsten.dominik@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=rpgoldman@sift.info \
/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).