Re: patch [Feature Addition] exporting comments on org files to html

["Eric Schulte" <schulte.eric@gmail.com>]

Carsten Dominik <dominik@science.uva.nl> writes:

> Hi Eric,
>
> before adding this, I would like to investigate with you if selective
> export (section 12.2 of the manual) could maybe used to achieve pretty
> much the same goal, with the only limiting condition that the part
> treated as a switchable comment does structurally have to be a
> subtree.
>

Hi Carsten,

That's really the motivation; the ability to embed a comment anywhere in
an org-mode file without changing the structure of the document.  Also I
liked the ability to change the colors of the comments based on the
initial string following the =#+begin_comment= part of the block.  Maybe
this would be more useful if it was generalized to selectively exporting
any =#+begin_*= type of block?

>
> Are you aware of selective export?  Maybe you could give us more
> detail about how you actually used this, and to what end?
>

We are building an application which has a web interface.  As we're in
the early stages we have been tracking todo's (and documenting the app)
with an org-mode file, which exports to the documentation of the
application and it times it is useful to export our comments as well.

Of course as this likely isn't generally useful I understand not pushing
it into the already busy org-exp.el file.

Thanks -- Eric

>
> - Carsten
>
>
> On Nov 5, 2008, at 7:50 AM, Eric Schulte wrote:
>
>> Hi,
>>
>> I have been co-authoring an org-mode file with a co-worker, and we
>> started to put comments in org-blocks with the following format
>>
>> #+begin_comment ems example comment
>> body of the comment
>> - a list inside
>> - of the comment
>> #+end_comment
>>
>> I made the following additions to org-exp.el (patch attached) which
>> allows the optional exportation of comment blocks through the use of a
>> `block-comments' option line in the file header.
>>
>> #+OPTIONS:   comment-blocks:t
>>
>> Currently it only exports to html, and it styles the blocks using css
>> (added to the org default html css styles).  It also adds id's to the
>> comment divs which include the authors name, so it's possible to style
>> the comments by their author (for example different colors by author).
>> I used something like the following to style our comments (our
>> initials
>> are wrg and ems).  I'm certainly no css expert, so I'm sure it's
>> possible to get much nicer looking comment blocks.
>>
>> ,----[comment-style.css]
>> | div#org-comment-wrg {
>> |   background: #cdecf8;
>> |   border: solid 1px #09abe7;
>> |   padding: 0.5em;
>> | }
>> |
>> | div#org-comment-ems {
>> |   background: #d1fbaf;
>> |   border: solid 1px #78ed19;
>> |   padding: 0.5em;
>> | }
>> `----
>>
>> Here's the patch to org-exp.el.  I'd love to hear any
>> ideas/issues/feedback.
>>
>> Cheers -- Eric
>>
>> diff --git a/lisp/org-exp.el b/lisp/org-exp.el
>> index 4be6b01..b3a848e 100644
>> --- a/lisp/org-exp.el
>> +++ b/lisp/org-exp.el
>> @@ -252,6 +252,11 @@ e.g. \"timestamp:nil\"."
>>   :group 'org-export-general
>>   :type 'boolean)
>>
>> +(defcustom org-export-comment-blocks nil
>> +  "If non-nil, export comment blocks"
>> +  :group 'org-export-general
>> +  :type 'boolean)
>> +
>> (defcustom org-export-with-tags 'not-in-toc
>>   "If nil, do not export tags, just remove them from headlines.
>> If this is the symbol `not-in-toc', tags will be removed from table of
>> @@ -519,6 +524,7 @@ Org-mode file."
>>                                white-space:nowrap; }
>>   .org-info-js_search-highlight {background-color:#ffff00;
>> color:#000000;
>>                                  font-weight:bold; }
>> +  .org-comment { background: #efefef; border: solid 1px; }
>>  ]]>
>> </style>"
>>   "The default style specification for exported HTML files.
>> @@ -817,6 +823,7 @@ or if they are only using it locally."
>>     (:footnotes            . org-export-with-footnotes)
>>     (:drawers              . org-export-with-drawers)
>>     (:tags                 . org-export-with-tags)
>> +    (:comment-blocks       . org-export-comment-blocks)
>>     (:TeX-macros           . org-export-with-TeX-macros)
>>     (:LaTeX-fragments      . org-export-with-LaTeX-fragments)
>>     (:skip-before-1st-heading . org-export-skip-text-before-1st-
>> heading)
>> @@ -962,7 +969,8 @@ modified) list.")
>> 		  ("skip"  . :skip-before-1st-heading)
>> 		  ("author" . :author-info)
>> 		  ("creator" . :creator-info)
>> -		  ("timestamp" . :time-stamp-file)))
>> +		  ("timestamp" . :time-stamp-file)
>> +		  ("comment-blocks" . :comment-blocks)))
>> 	    o)
>> 	(while (setq o (pop op))
>> 	  (if (string-match (concat (regexp-quote (car o))
>> @@ -1436,6 +1444,9 @@ on this string to produce the exported version."
>>
>>       ;; Handle source code snippets
>>       (org-export-replace-src-segments)
>> +
>> +      ;; Handle comment environment and comment subtrees
>> +      (org-export-handle-comment-blocks-and-subtrees (plist-get
>> parameters :comment-blocks))
>>
>>       ;; Get rid of drawers
>>       (org-export-remove-or-extract-drawers drawers
>> @@ -1478,10 +1489,6 @@ on this string to produce the exported
>> version."
>>       ;; Blockquotes and verse
>>       (org-export-mark-blockquote-and-verse)
>>
>> -      ;; Remove comment environment and comment subtrees
>> -      (org-export-remove-comment-blocks-and-subtrees)
>> -
>> -
>>       ;; Find matches for radio targets and turn them into internal
>> links
>>       (org-export-mark-radio-links)
>>
>> @@ -1783,15 +1790,21 @@ These special cookies will later be
>> interpreted by the backend."
>> 		       "ORG-VERSE-END" "ORG-VERSE-START")
>> 		   t t)))
>>
>> -(defun org-export-remove-comment-blocks-and-subtrees ()
>> -  "Remove the comment environment, and also commented subtrees."
>> +(defun org-export-handle-comment-blocks-and-subtrees (comment-blocks)
>> +  "Prepare comment blocks and comment subtrees for export.  If
>> +COMMENT-BLOCKS is non-nil then format comment blocks using
>> +`org-export-format-comment', otherwise hide all comment blocks
>> +during export.  Hides all comment subtrees."
>>   (let ((re-commented (concat "^\\*+[ \t]+" org-comment-string "\\>"))
>> -        (case-fold-search nil))
>> +        (case-fold-search t))
>>     ;; Remove comment environment
>>     (goto-char (point-min))
>>     (while (re-search-forward
>> -	    "^#\\+BEGIN_COMMENT[ \t]*\n[^\000]*?^#\\+END_COMMENT\\>.*"
>> nil t)
>> -      (replace-match "" t t))
>> +	    "^#\\+begin_comment\\([ \t]+\\(\\S-+\\)\\)?[
>> \t]*\\(.*\\)?[\r
>> \n]\\([^\000]*?\\)#\\+end_comment"
>> +	    nil t)
>> +      (replace-match (if comment-blocks
>> +			 (org-export-format-comment (match-string 4)
>> (match-string 2) (match-string 3))
>> +			 "") t t))
>>     ;; Remove subtrees that are commented
>>     (goto-char (point-min))
>>     (while (re-search-forward re-commented nil t)
>> @@ -2170,6 +2183,34 @@ backends, it converts the segment into an
>> EXAMPLE segment."
>> 	      (if (string-match "\n\\'" code) "" "\n")
>> 	      "#+END_EXAMPLE\n")))))
>>
>> +(defun org-export-format-comment (body &optional owner title)
>> +  "Format comment BODY by OWNER and return it formatted for export.
>> +Currently, this only does something for HTML export, for all
>> +other backends, it converts the comment into an EXAMPLE segment."
>> +  (save-match-data
>> +    (cond
>> +      (htmlp ;; We are exporting to HTML
>> +       (concat "#+BEGIN_HTML\n"
>> +	       "<div class=\"org-comment\" "
>> +	       (if owner (format "id=\"org-comment-%s\" " owner))
>> +	       ">\n"
>> +	       (if owner (concat "<b>" owner "</b> ") "")
>> +	       (if (and title (> (length title) 0)) (concat " -- "
>> title "</br>\n") "</br>\n")
>> +	       "<p>\n"
>> +	       "#+END_HTML\n"
>> +	       body
>> +	       "#+BEGIN_HTML\n"
>> +	       "</p>\n"
>> +	       "</div>\n"
>> +	       "\n#+END_HTML\n"))
>> +      (t ;; This is not HTML, so just make it an example.
>> +       (concat "#+BEGIN_EXAMPLE\n"
>> +	       (if title (concat "Title:" title "\n") "")
>> +	       (if owner (concat "By:" owner "\n") "")
>> +	       body
>> +	       (if (string-match "\n\\'" body) "" "\n")
>> +	       "#+END_EXAMPLE\n")))))
>> +
>> ;;; ASCII export
>>
>> (defvar org-last-level nil) ; dynamically scoped variable
>> @@ -2250,6 +2291,7 @@ underlined headlines.  The default is 3."
>> 		  :verbatim-multiline t
>> 		  :select-tags (plist-get opt-plist :select-tags)
>> 		  :exclude-tags (plist-get opt-plist :exclude-tags)
>> +		  :comment-blocks (plist-get opt-plist :comment-blocks)
>> 		  :archived-trees
>> 		  (plist-get opt-plist :archived-trees)
>> 		  :add-text (plist-get opt-plist :text))
>> @@ -2924,7 +2966,9 @@ PUB-DIR is set, use this as the publishing
>> directory."
>> 	    :add-text
>> 	    (plist-get opt-plist :text)
>> 	    :LaTeX-fragments
>> -	    (plist-get opt-plist :LaTeX-fragments))
>> +	    (plist-get opt-plist :LaTeX-fragments)
>> +	    :comment-blocks
>> +	    (plist-get opt-plist :comment-blocks))
>> 	   "[\r\n]"))
>> 	 table-open type
>> 	 table-buffer table-orig-buffer
>> _______________________________________________
>> Emacs-orgmode mailing list
>> Remember: use `Reply All' to send replies to the list.
>> Emacs-orgmode@gnu.org
>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode