1 #+OPTIONS: H:3 num:nil toc:t \n:nil @:t ::t |:t ^:nil -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP: align fold nodlcheck hidestars oddeven lognotestate
3 #+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS: Write(w) Update(u) Fix(f) Check(c)
5 #+TITLE: Ongoing Development of Org Additions?
7 #+EMAIL: bzg AT altern DOT org
12 #+LINK: fireforgrepofile http://repo.or.cz/w/org-fireforg.git?a=blob_plain;f=%s;hb=HEAD
14 # This file is the default header for new Org files in Worg. Feel free
15 # to tailor it to your needs.
17 [[file:index.org][{Back to Worg's index}]]
20 Some org-mode related project currently being developed in worg.
25 Located in the =contrib/lisp/= directory of org-mode.
27 A utility for collecting properties from the headers in an org file,
28 running the properties through arbitrary elisp functions, and
29 presenting the results in a table.
31 The functionality of this tool is similar to the functionality of
32 [[info:org:Capturing%20column%20view][info:org:Capturing column view]], but this has support for processing
33 prior to the generation of the table.
35 Here is a simple example application of this utility.
37 #+begin_comment ems better example
38 it might be better to put an exercise example here if someone has one.
41 #+BEGIN: propview :id "data" :cols (ITEM f d list (apply '* list) (+ f d))
54 :list: '(9 2 3 4 5 6 7)
80 * Fireforg, a Firefox extension for org interaction (EXPERIMENTAL)
81 Fireforg is a Firefox extension, that interacts with Emacs Org-mode.
83 For the displayed URL it shows the associated tags in the status bar
84 and allows to show a list of annotations that can be instantly visited
87 Additionally, in every website it marks all links that occur in the agenda files.
89 For every link in the agenda files the previous heading and its tags
90 are associated with it.
92 For *scientific use*, it is possible to *send BibTeX entries* for
93 sites supported by the Zotero plugin to Emacs. [[*Import%20BibTeX%20using%20Zotero][Additional steps]] are
94 necessary for this to work.
98 :ID: 13179b21-d70a-4255-a8f1-9f4e4e729074
100 The following notes should be taken into consideration before using Fireforg:
101 - On the Emacs side a registry of all links in the agenda files will
102 be generated and saved in plain text onto the harddrive.
103 - The generation can take very a long time depending on the size of
104 the agenda files and the number of links in them.
105 - The generated file can become quite large.
106 - When files are *encrypted* having some information from them in
107 plain text on the harddrive might not be what you want.
108 - Firefox will read and look through the registry file for the
109 currently viewed site. Depending on the size of the registry file
110 and on the options [[id:e77f15a8-c358-44fd-a207-8c422fee2d1e][Lookup links on page load]] and [[id:d73476f3-6c09-479c-abea-f33d3e0e074a][Prefetch links to extract DOI]]
111 this might slow down the browsing experience.
115 - Install org-protocol according to its [[file:org-contrib/org-protocol.org][manual]] and *please verify
116 that it's working* using either the bookmarks or by invoking it directly in the shell:
117 : emacsclient 'org-protocol://remember://w/http%3A%2F%2Forgmode.org%2F/Org-Mode%3A%20Your%20Life%20in%20Plain%20Text%20-%20Mozilla%20Firefox/'
118 - Get org-fireforg.el from [[fireforgrepofile:lisp/org-fireforg.el][here]] and put the following into your
119 =.emacs= *after* the section that initializes org-protocol:
120 : (add-to-list 'load-path "~/path/to/org/fireforg/")
121 : (require 'org-fireforg)
122 : (org-fireforg-registry-insinuate)
124 and as the last line of the file:
125 : (org-fireforg-registry-initialize t)
127 Note that creating the registry can take a long time depending on
128 the size of the agenda files and the number of links in them.
130 - Visit [[fireforgrepofile:build/fireforg.xpi][this link]] with Firefox, confirm installation of the extension and restart.
132 (Windows users will have to adjust: org-fireforg-registry-file-xml in Emacs
133 and "registry-file" in Fireforgs preferences to be the same file.)
135 *** Installation from a git clone
137 It is also possible to clone the git repository first, using:
138 : git clone http://repo.or.cz/r/org-fireforg.git
139 , install lisp/org-fireforg.el according to the instructions above
140 and add a file named =fireforg@burtzlaff.de= containing the path
141 to the "fireforg" subdirectory into =~/.mozilla/firefox/<your
142 profile>/extensions/=.
144 In my setup for example there is a file
145 =~/.mozilla/firefox/4xyx9l73.default/extensions/fireforg@burtzlaff.de=
147 : /home/andy/projects/org-fireforg/fireforg
149 A restart of Firefox is required for this to work.
152 *** The status bar entry
154 If the currently viewed url is found in your agenda files, the number
155 of occurrences together with all associated tags will be shown in the
156 status bar. A left click on the status bar entry will show a list of
157 all headings associated with the currently viewed url. Selecting one
158 of them lets Emacs visit that heading.
160 For example, this heading in one of your agenda files:
161 : * Greatest tool in the world [[http://orgmode.org/][Org mode]] :Org:
162 will yield the following when visiting http://orgmode.org/ and left clicking:
164 [[file:images/screenshots/org-fireforg-screenshot.png]]
166 *** Triggering store-link and remember
167 Right clicking on the status bar entry shows a menu that let's you
168 trigger org-protocol's "store-link" and "remember".
170 There is an entry for every remember template listed in the [[*List%20of%20characters%20specifying%20available%20remember%20templates][preferences]].
172 The entries in the submenu "All tabs" will call remember for every tab
173 in the current window. This option only makes sense if a remember
174 template is used, that stores the note automatically ("%!" in the template string), e.g.:
175 : * %:description \n %:link %!
177 *** Mark links that occur in the agenda files in websites
179 Whenever a site is loaded, Fireforg will alter the style of all links
180 in it, that occur in the agenda files. The tooltip of those links is
181 set to contain the annotations.
183 This feature can be turned off using an [[*Lookup%20links%20on%20page%20load][option]] in the [[*Preferences][preferences
184 dialog]]. [[*CSS%20style%20string%20for%20links%20with%20annotations][The CSS-style]] used for marking the link and [[*Overwrite%20tooltip%20for%20links%20with%20annotations][whether or
185 not the tooltip is set]] is also customizable.
187 *** Context menu for links
189 The context menu (accessible by right clicking on a link) has a
190 submenu "Fireforg", where all annotations for that link are listed:
192 [[file:images/screenshots/org-fireforg-screenshot-context-menu.png]]
194 ** Import BibTeX using Zotero
196 :ID: e6fc94c6-7fef-4348-b998-f6a6f58eded8
198 Fireforg is able to retrieve BibTex entries for the all sites
199 supported by [[http://www.zotero.org/][Zotero]]. To achieve this the following additional steps
201 - Install Zotero 1.0.10 from the [[http://www.zotero.org/][Zotero Website]]
202 - Set "Inject Zotero" in Fireforg's preference dialog
203 [fn:ffprefdiag: Fireforg's preference dialogue is accessible in
204 Firefox's menu under Tools->Add-ons->Fireforg->Preferences].
206 *Warning: On restart a small function is injected into Zotero to
207 catch imported entries. The change to the code is minimal and
208 non-permanent. In a worst case scenario Zotero's database might
209 get corrupted, though that hasn't happened yet.*
213 Whenever a single entry (*not* a collection) is imported into Zotero -
214 e.g. by clicking the white "document" symbol that appears to the right
215 in the url bar if Zotero supports importing the current site - it is
216 automatically exported to BibTeX and sent to org mode using
217 org-protocol. In Emacs it is put into the kill ring in a format
218 depending on the variable =org-fireforg-received-bibtex-format=:
220 - =nil=: The BibTeX entry is passed directly into the kill ring.
221 - =heading= (Default): A heading is generated with the BibTeX
222 fields as properties with prefix "BIB_":
223 : * [[<link to site>][<Title>]]
225 : :CUSTOM_ID: <BibTeX key>
226 : :BIB_entryType: <article, ...>
231 - =headingWithPropsAndBibTeXContent=: a heading with properties as
232 described above is generated and the entry in BibTeX format is
234 - =headingWithBibTeXContent=: same as the previous one but without the properties
236 If the 'url' field is a *static URL*, the link to it will be highlighted
237 in search results in every search engine. Otherwise the option
238 [[id:3ab02821-03c4-4fa7-9a3a-e9701245c5d8][Match sites by comparing their DOI with saved bibliography entries]] might help.
240 To export BibTeX information from all headings in the current buffer
241 with at least the "BIB_entryType" property call:
242 - =org-fireforg-export-bibtex-to-file= to export to a file
243 - =org-fireforg-export-bibtex-to-new-buffer= to export into a new buffer
245 *** Digital Object Identifiers (DOI)
247 :ID: fbd09ba5-6632-40df-bcc0-8e5a7b9eb7a7
249 If a BibTeX entry contains a field 'doi', a URL will be generated by
250 prepending "http://dx.doi.org/" to the corresponding property
251 'BIB_doi'. It will be handled as any other URL. There is a
252 [[id:3ab02821-03c4-4fa7-9a3a-e9701245c5d8][corresponding functionality in the plugin]] that allows to associated
253 pages despite non-static URLs.
255 Fireforg's preference dialogue is accessible in Firefox's menu
256 under Tools->Add-ons->Fireforg->Preferences
258 The file containing an xml tree with all link-headline associations
259 generated from the agenda files. You should not need to change
260 this. It has to be same as the customizable variable
261 =org-fireforg-registry-file-xml= in Emacs.
262 ***** Lookup links on page load
264 :ID: e77f15a8-c358-44fd-a207-8c422fee2d1e
266 When enabled, all links in a web page that have headlines
267 associated with them are marked. This is achieve by adding the
268 following CSS style string to the element:
269 Depending on the size of the registry this *might slow Firefox down*.
270 ***** CSS style string for links with annotations
271 The string that is appended to the CSS =style= string of a link
272 element, if annotations for it exist.
273 ***** Overwrite tooltip for links with annotations
274 If enabled, sets the tooltip for the links, for which
275 annotations exist to contain those annotations.
277 After restarting Firefox, a function in the Zotero code gets altered
278 so that all BibtTeX entries (*not* collections) that are imported are
279 sent using org-protocol and are handled in Emacs according to the
280 variable =org-fireforg-received-bibtex-format= as described [[* Import BibTeX using Zotero][here]]. Due
281 to [[* Technical note][design choices in Zotero]] this is a bit fragile and can yield errors
282 and *might possibly even break Zotero's database*. It is not advisable
283 to use Zotero for production when enabling this option in Fireforg.
284 ***** Match sites by comparing their DOI with saved bibliography entries
286 :ID: 3ab02821-03c4-4fa7-9a3a-e9701245c5d8
288 Extract the Digital Object Identifier (DOI) from a page, prepend
289 "http://dx.doi.org/" to it and look up the resulting URL.
291 If using a bibliography format [[id:e6fc94c6-7fef-4348-b998-f6a6f58eded8][with properties]], a [[id:fbd09ba5-6632-40df-bcc0-8e5a7b9eb7a7][URL is
292 generated in the same way from the value of the field "BIB_doi"
293 if it exists]]. Thus documents can be matched regardless of the
294 possibly non-static URL.
295 ***** Prefetch links to extract DOI
297 :ID: d73476f3-6c09-479c-abea-f33d3e0e074a
299 *Prefetch all links in a page* after it is loaded, extract the
300 DOIs - if any - and [[id:fbd09ba5-6632-40df-bcc0-8e5a7b9eb7a7][use it to find annotations]]. This requires
301 the option [[id:3ab02821-03c4-4fa7-9a3a-e9701245c5d8][Match sites by comparing their DOI with saved
302 bibliography entries]] to be set.
304 A site is only prefetched once in every Firefox session, because the
305 associated URL mapping is saved until Firefox is restarted.
307 *All links starting with "http" will be prefetched (except for
308 files with extensions: PDF, GIF, PNG or SWF).* This option can
309 also be toggled in the status bar menu.
311 *This option will generate additional network traffic and might
312 slow the browsing experience*
313 ***** List of characters specifying available remember templates
314 For every character in this list an entry in the [[*Triggering%20store%20link%20and%20remember][popup menu]] will
315 be generated, that triggers remember with the template
316 associated with the character.
317 ***** Enable workaround for Mac
318 see [[* Workaround for the inability to register a protocol in Firefox on the Mac][here]]
319 ***** Temporary file for Mac workaround
320 see [[* Workaround for the inability to register a protocol in Firefox on the Mac][here]]
322 ** Workaround for the inability to register a protocol in Firefox on the Mac
324 A long known bug in Firefox on the Mac is reported to stop protocol
325 registration from working. To work around this Fireforg is able to
326 write the org-protocol urls to a temporary file, that is read every
327 second and, if non empty, passed to emacsclient and emptied.
330 - check "Enable workaround for Mac" in Fireforg's preference dialogue [fn:ffprefdiag]
331 - get pull.sh from [[http://repo.or.cz/w/org-fireforg.git?a=blob_plain;f=ff_mac_workaround/pull.sh;hb=HEAD][the repository]] and run it.
335 To avoid confusion, always update both org-fireforg.el and the plugin.
337 The plugin has to be uninstalled and then reinstalled as described
338 above. Automatic updating will be used when the testing phase is over.
340 ** Bugreporting and discussion
342 - Discussions go to the org-mode list.
343 - Bugreports are better not sent to the list, but rather directly to
344 the [[mailto:andreas%20AT%20burtzlaff%20DOT%20de][author]] (Please add "[Fireforg]" to the subject.).
346 *** A checklist for bug tracing
348 To create a test case put:
349 : * Greatest tool in the world [[http://orgmode.org/][Org mode]] :Org:
350 into one of your agenda files and save it.
352 If problems arise please go through this checklist to locate the problem:
354 - Does the file "~/.org-fireforg-registry.xml" exist and does it contain "orgmode.org"?
355 - *No on either*: Send me the last content of the Messages buffer in Emacs
356 - *Yes*: In the Firefox menu: "Tools"->"Error console" look for
357 errors containing: "chrome://fireforg/" and send them to me.
361 Different instances of Zotero's Translator object seem to share state
362 in a non-obvious way. This makes coding very fragile and even lets
363 some imports fail (silently) after Fireforg has injected its code. The
364 failure when importing collections is somehow related to this. While
365 I find it a strange design choice, it is not in my power to change it.
366 * MEMO org-mail-htmlize: Create MIME messages based on Org
368 ** Representing a MIME internet message
370 A MIME internet message consists of one or more MIME entities. Each
371 MIME entity is of a distinct type and subtype, has a body and
372 optional MIME headers related to it's content.
374 A MIME entity is represented as a list:
376 (TYPE SUBTYPE BODY CONT-HEAD)
378 - TYPE :: Symbol of MIME media type (e.g. text, video, audio).
380 - SUBTYPE :: Symbol of MIME media subtype (e.g. plain, html).
382 - BODY :: String with entity body -or- list of other MIME entities.
384 - CONT-HEAD :: List of cons with content related MIME header
385 fields. The name of the header field without the
386 prefix "Content-" is car, the value cdr.
390 #+begin_src emacs-lisp
391 '(text html "<h1>Headline</h1>" ((disposition . inline)))
394 For messages of type multipart the body consists of a list of one
395 or more MIME entities.
397 #+begin_src emacs-lisp
398 '(multipart alternative
399 '((text plain "* Headline")
400 (text html "<h1>headline</h1>")))
403 ** MIME delimiters of SEMI and mml
405 The MIME delimiters are defined in an association list with a
406 symbol of the library's name as key and delimiter format strings as
407 values. For each library there are three formatstrings.
409 (SYMBOL DELIM-SINGLE DELIM-SINGLE-CONT DELIM-MULTI)
411 - DELIM-SINGLE :: Denoting a single MIME entity.
413 Strings are passed in this order:
423 - DELIM-SINGLE-CONT :: Format of content header strings.
425 Strings are passed in this order:
429 2. header field value
431 - DELIM-MULTI :: Enclosing parts of a multipart entity.
433 Strings are passed in this order:
441 #+begin_src emacs-lisp
442 (setq org-mail-htmlize-mime-delimiter-alist
443 '((semi "\n--[[%s/%s%s]]\n%s" "\ncontent-%s: %s" "\n--<<%s>>-{\n%s\n--}-<<%s>>")
444 (mml "\n<#part type=\"%s/%s\"%s>\n%s" " %s=\"%s\"" "\n<#multipart type=\"%s\">\n%s\n<#/multipart>")))
449 This generic function returns a string representation with MIME
450 delimiters depending on the variable =org-mail-htmlize-mime-lib=.
452 #+begin_src emacs-lisp
453 (setq org-mail-htmlize-mime-lib 'semi)
456 #+begin_src emacs-lisp
457 (defun org-mail-htmlize-mime-entity (type subtype body
459 "Return string representation of MIME entity.
461 TYPE is the type of entity body.
462 SUBTYPE is the subtype of body.
463 BODY is the body of the entity. Either a string with the body
464 content or a list with one ore more MIME entities.
465 Optional argument CONT-HEAD is a list of cons with content
466 specific headers, name in car and value in cdr."
467 (let ((delimlst (assoc org-mail-htmlize-mime-lib
468 org-mail-htmlize-mime-delimiter-alist)))
469 (if (eq type 'multipart)
470 (format (nth 3 delimlst) subtype
471 (mapconcat '(lambda (b)
472 (apply 'org-mail-htmlize-mime-entity
473 (car b) (cadr b) (cddr b)))
476 (format (nth 1 delimlst)
478 (mapconcat '(lambda (h)
479 (format (nth 2 delimlst) (car h) (cdr h)))
486 *** How to handle charset information?
488 *** How to attach files?
490 The generic function expects BODY either be a string or a list.
491 Attaching binary file (image, etc.) requires to encode it so the
492 message will pass the message system. So we /might/ use kind of a
493 encoder (e.g. base64) on our own.
495 Or, what seems a cleaner solution: Use attachment function of the
496 respective MIME mode. To achive this: Introduce third possibility
497 for BODY: A cons with the filename in car and symbol of the
500 (FILENAME . FUNCTION)
502 #+begin_src emacs-lisp
503 '(image jpeg ("/path/to/image" . org-mail-htmlize-add-attachment))
506 The function =org-mail-htmlize-add-attachment= is called with file
507 name as argument and calls the appropriate function depending on
508 =org-mail-htmlize-mime-lib= and returns a string
510 - with the encoded body
514 - the complete MIME entity
516 Side effect: The user might be prompted for attachment settings
517 (e.g. encoding). But, on the other hand: We delegate the job of
518 creating the attachment to the library that is responsible for
521 ** Quotes from the specs
523 *** MIME multipart: Notion of structured, related body parts
525 :Created: [2010-03-25 Do]
528 - [[http://tools.ietf.org/html/rfc2046.html#section-5.1.1][RFC2046, 5.1.1]]
531 NOTE: Conspicuously missing from the "multipart" type is a notion of
532 structured, related body parts. It is recommended that those wishing
533 to provide more structured or integrated multipart messaging
534 facilities should define subtypes of multipart that are syntactically
535 identical but define relationships between the various parts. For
536 example, subtypes of multipart could be defined that include a
537 distinguished part which in turn is used to specify the relationships
538 between the other parts, probably referring to them by their
539 Content-ID field. Old implementations will not recognize the new
540 subtype if this approach is used, but will treat it as
541 multipart/mixed and will thus be able to show the user the parts that
544 *** MIME multipart: order of entities inside a multipart
546 :Created: [2010-03-25 Do]
549 - [[http://tools.ietf.org/html/rfc2046.html#section-5.1.3][RFC2046, 5.1.3]]
554 The "mixed" subtype of "multipart" is intended for use when the body
555 parts are independent and need to be bundled in a particular order.
556 Any "multipart" subtypes that an implementation does not recognize
557 must be treated as being of subtype "mixed".
561 - [[http://tools.ietf.org/html/rfc2046.html#section-5.1.4][RFC2046, 5.1.4]]
564 5.1.4. Alternative Subtype
566 The "multipart/alternative" type is syntactically identical to
567 "multipart/mixed", but the semantics are different. In particular,
568 each of the body parts is an "alternative" version of the same
571 Systems should recognize that the content of the various parts are
572 interchangeable. Systems should choose the "best" type based on the
573 local environment and references, in some cases even through user
574 interaction. As with "multipart/mixed", the order of body parts is
575 significant. In this case, the alternatives appear in an order of
576 increasing faithfulness to the original content. In general, the
577 best choice is the LAST part of a type supported by the recipient
578 system's local environment.
582 In general, user agents that compose "multipart/alternative" entities
583 must place the body parts in increasing order of preference, that is,
584 with the preferred format last. For fancy text, the sending user
585 agent should put the plainest format first and the richest format
586 last. Receiving user agents should pick and display the last format
587 they are capable of displaying. In the case where one of the
588 alternatives is itself of type "multipart" and contains unrecognized
589 sub-parts, the user agent may choose either to show that alternative,
590 an earlier alternative, or both.
592 * Org mode issue tracking library
594 A collection of helper functions to maintain the [[file:org-issues.org][Issue file]] from
595 within Wanderlust and (partly) Gnus.
597 You can download a current version of this file [[file:elisp/org-issue.el][here]].
599 Currently following commands are provided:
601 - `org-issue-new' :: File a new issue for current message
603 Creates a new TODO in `org-issue-issue-file' below the headline
604 "New Issues" with keyword NEW. If customization variable
605 `org-issue-message-flag' is non-nil and flagging messages is
606 supported, the message of this issue is flagged.
608 - `org-issue-close' :: Close issue of current message.
610 - `org-issue-tag' :: Tag issue of current message.
612 - `org-issue-update-message-flag' :: Update message flag according
615 If the issue for current message is closed, the message flag is
618 - `org-issue-link-gmane' :: An Org mode web link pointing to current
619 message on gmane is pushed to killring and clipboard.