Re: [Orgmode] Re: OrgmodeOrg-export-generic and wikis...
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 rpgold...@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-exportnil :toc-exportnil :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-wrapnil :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-paragrapht )) 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
Re: [Orgmode] Re: OrgmodeOrg-export-generic and wikis...
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 rpgold...@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-exportnil :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-wrapnil :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-paragrapht )) 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 ___ Emacs-orgmode mailing list Please use `Reply All' to send replies to the list. Emacs-orgmode@gnu.org http://lists.gnu.org/mailman/listinfo/emacs-orgmode
Re: [Orgmode] Re: OrgmodeOrg-export-generic and wikis...
On Apr 29, 2010, at 3:57 PM, Wes Hardaker wrote: On Wed, 28 Apr 2010 14:38:47 -0500, Robert Goldman rpgold...@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. - Carsten RG 2. Is the existing handle each line separately algorithm going to RG permit us to handle faces correctly? Seems like we'll need a lot of RG hair to handle, e.g., a phrase in italics that straddles a line- break, RG won't we? Well, that's a good question and one I don't have a great answer for. We could switch the parser to be multi-line based regexp matches but I suspect the complexity of when to stop those regexps will get rather harry too! -- Wes Hardaker My Pictures: http://capturedonearth.com/ My Thoughts: http://pontifications.hardakers.net/ ___ Emacs-orgmode mailing list Please use `Reply All' to send replies to the list. Emacs-orgmode@gnu.org http://lists.gnu.org/mailman/listinfo/emacs-orgmode - Carsten ___ Emacs-orgmode mailing list Please use `Reply All' to send replies to the list. Emacs-orgmode@gnu.org http://lists.gnu.org/mailman/listinfo/emacs-orgmode
Re: [Orgmode] Re: OrgmodeOrg-export-generic and wikis...
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 rpgold...@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-exportnil :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-wrapnil :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-paragrapht )) 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 ___ Emacs-orgmode mailing list Please use `Reply All' to send replies to the list. Emacs-orgmode@gnu.org http://lists.gnu.org/mailman/listinfo/emacs-orgmode
