org-devel.org

   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?
   6 #+AUTHOR:     Worg people
   7 #+EMAIL:      mdl AT imapmail DOT org
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg
  11
  12 #+LINK: fireforgrepofile http://repo.or.cz/w/org-fireforg.git?a=blob_plain;f=%s;hb=HEAD
  13
  14 # This file is the default header for new Org files in Worg.  Feel free
  15 # to tailor it to your needs.
  16
  17 [[file:index.org][{Back to Worg's index}]]
  18
  19
  20 Some org-mode related project currently being developed in worg.
  21
  22
  23 * Org Collector
  24
  25 Located in the =contrib/lisp/= directory of org-mode.
  26
  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.
  30
  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.
  34
  35 Here is a simple example application of this utility.
  36
  37 #+begin_comment ems better example
  38 it might be better to put an exercise example here if someone has one.
  39 #+end_comment
  40
  41 #+BEGIN: propview :id "data" :cols (ITEM f d list (apply '* list) (+ f d))
  42
  43 #+END:
  44
  45 *** Example Data
  46       :PROPERTIES:
  47       :ID:       data
  48       :END:
  49
  50 ****** run1
  51       :PROPERTIES:
  52       :d: 33
  53       :f: 2
  54       :list: '(9 2 3 4 5 6 7)
  55       :END:
  56
  57
  58 ****** run2
  59       :PROPERTIES:
  60       :d: 34
  61       :f: 4
  62       :END:
  63
  64
  65 ****** run3
  66       :PROPERTIES:
  67       :d: 35
  68       :f: 4
  69       :END:
  70
  71
  72 ****** run4
  73       :PROPERTIES:
  74       :d: 36
  75       :f: 2
  76       :END:
  77
  78
  79 #<<fireforg>>
  80 * Fireforg, a Firefox extension for org interaction (EXPERIMENTAL)
  81 Fireforg is a Firefox extension, that interacts with Emacs Org-mode.
  82
  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
  85 in Emacs.
  86
  87 Additionally, in every website it marks all links that occur in the agenda files.
  88
  89 For every link in the agenda files the previous heading and its tags
  90 are associated with it.
  91
  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.
  95
  96 ** Caveats
  97    :PROPERTIES:
  98    :ID:       13179b21-d70a-4255-a8f1-9f4e4e729074
  99    :END:
 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.
 112
 113 ** Installation
 114
 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)
 123
 124      and as the last line of the file:
 125      : (org-fireforg-registry-initialize t)
 126
 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.
 129
 130    - Visit [[fireforgrepofile:build/fireforg.xpi][this link]] with Firefox, confirm installation of the extension and restart.
 131
 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.)
 134
 135 *** Installation from a git clone
 136
 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/=.
 143
 144     In my setup for example there is a file
 145     =~/.mozilla/firefox/4xyx9l73.default/extensions/fireforg@burtzlaff.de=
 146     containing
 147     : /home/andy/projects/org-fireforg/fireforg
 148
 149     A restart of Firefox is required for this to work.
 150
 151 ** Basic usage
 152 *** The status bar entry
 153
 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.
 159
 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:
 163
 164     [[file:images/screenshots/org-fireforg-screenshot.png]]
 165
 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".
 169
 170     There is an entry for every remember template listed in the [[*List%20of%20characters%20specifying%20available%20remember%20templates][preferences]].
 171
 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 %!
 176
 177 *** Mark links that occur in the agenda files in websites
 178
 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.
 182
 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.
 186
 187 *** Context menu for links
 188
 189     The context menu (accessible by right clicking on a link) has a
 190     submenu "Fireforg", where all annotations for that link are listed:
 191
 192     [[file:images/screenshots/org-fireforg-screenshot-context-menu.png]]
 193
 194 ** Import BibTeX using Zotero
 195    :PROPERTIES:
 196    :ID:       e6fc94c6-7fef-4348-b998-f6a6f58eded8
 197    :END:
 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
 200    are necessary:
 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].
 205
 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.*
 210
 211    - Restart Firefox
 212
 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=:
 219
 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>]]
 224      :  :PROPERTIES:
 225      :   :CUSTOM_ID: <BibTeX key>
 226      :   :BIB_entryType: <article, ...>
 227      :   :BIB_author: ...
 228      :   :BIB_title: ...
 229      :   ...
 230      :   :END:
 231    - =headingWithPropsAndBibTeXContent=: a heading with properties as
 232      described above is generated and the entry in BibTeX format is
 233      appended.
 234    - =headingWithBibTeXContent=: same as the previous one but without the properties
 235
 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.
 239
 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
 244
 245 *** Digital Object Identifiers (DOI)
 246     :PROPERTIES:
 247     :ID:       fbd09ba5-6632-40df-bcc0-8e5a7b9eb7a7
 248     :END:
 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.
 254 ** Preferences
 255    Fireforg's preference dialogue is accessible in Firefox's menu
 256    under Tools->Add-ons->Fireforg->Preferences
 257 ***** Registry file
 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
 263       :PROPERTIES:
 264       :ID:       e77f15a8-c358-44fd-a207-8c422fee2d1e
 265       :END:
 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.
 276 ***** Inject Zotero
 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
 285       :PROPERTIES:
 286       :ID:       3ab02821-03c4-4fa7-9a3a-e9701245c5d8
 287       :END:
 288       Extract the Digital Object Identifier (DOI) from a page, prepend
 289       "http://dx.doi.org/" to it and look up the resulting URL.
 290
 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
 296       :PROPERTIES:
 297       :ID:       d73476f3-6c09-479c-abea-f33d3e0e074a
 298       :END:
 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.
 303
 304       A site is only prefetched once in every Firefox session, because the
 305       associated URL mapping is saved until Firefox is restarted.
 306
 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.
 310
 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]]
 321
 322 ** Workaround for the inability to register a protocol in Firefox on the Mac
 323
 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.
 328
 329    To enable this:
 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.
 332
 333 ** Updating
 334
 335    To avoid confusion, always update both org-fireforg.el and the plugin.
 336
 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.
 339
 340 ** Bugreporting and discussion
 341
 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.).
 345
 346 *** A checklist for bug tracing
 347
 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.
 351
 352     If problems arise please go through this checklist to locate the problem:
 353
 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.
 358
 359 ** Technical note
 360
 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
 367
 368 ** Representing a MIME internet message
 369
 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.
 373
 374    A MIME entity is represented as a list:
 375
 376    (TYPE SUBTYPE BODY CONT-HEAD)
 377
 378    - TYPE :: Symbol of MIME media type (e.g. text, video, audio).
 379
 380    - SUBTYPE :: Symbol of MIME media subtype (e.g. plain, html).
 381
 382    - BODY :: String with entity body -or- list of other MIME entities.
 383
 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.
 387
 388    Example:
 389
 390    #+begin_src emacs-lisp
 391    '(text html "<h1>Headline</h1>" ((disposition . inline)))
 392    #+end_src
 393
 394    For messages of type multipart the body consists of a list of one
 395    or more MIME entities.
 396
 397    #+begin_src emacs-lisp
 398      '(multipart alternative
 399                  '((text plain "* Headline")
 400                    (text html "<h1>headline</h1>")))
 401    #+end_src
 402
 403 ** MIME delimiters of SEMI and mml
 404
 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.
 408
 409    (SYMBOL DELIM-SINGLE DELIM-SINGLE-CONT DELIM-MULTI)
 410
 411    - DELIM-SINGLE :: Denoting a single MIME entity.
 412
 413                      Strings are passed in this order:
 414
 415                      1. type
 416
 417                      2. subtype
 418
 419                      3. content header
 420
 421                      4. body
 422
 423    - DELIM-SINGLE-CONT :: Format of content header strings.
 424
 425         Strings are passed in this order:
 426
 427         1. header field name
 428
 429         2. header field value
 430
 431    - DELIM-MULTI :: Enclosing parts of a multipart entity.
 432
 433                     Strings are passed in this order:
 434
 435                     1. subtype
 436
 437                     2. body
 438
 439                     3. subtype
 440
 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>")))
 445    #+end_src
 446
 447 ** Generic function
 448
 449    This generic function returns a string representation with MIME
 450    delimiters depending on the variable =org-mail-htmlize-mime-lib=.
 451
 452    #+begin_src emacs-lisp
 453      (setq org-mail-htmlize-mime-lib 'semi)
 454    #+end_src
 455
 456    #+begin_src emacs-lisp
 457      (defun org-mail-htmlize-mime-entity (type subtype body
 458                                                &optional cont-head)
 459        "Return string representation of MIME entity.
 460
 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)))
 474                                 body "")
 475                      subtype)
 476            (format (nth 1 delimlst)
 477                    type subtype
 478                    (mapconcat '(lambda (h)
 479                                  (format (nth 2 delimlst) (car h) (cdr h)))
 480                               cont-head "")
 481                    body))))
 482    #+end_src
 483
 484 ** Open questions
 485
 486 *** How to handle charset information?
 487
 488 *** How to attach files?
 489
 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.
 494
 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
 498     function in cdr.
 499
 500     (FILENAME . FUNCTION)
 501
 502     #+begin_src emacs-lisp
 503       '(image jpeg ("/path/to/image" . org-mail-htmlize-add-attachment))
 504     #+end_src
 505
 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
 509
 510        - with the encoded body
 511
 512          -or-
 513
 514        - the complete MIME entity
 515
 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
 519     mime.
 520
 521 ** Quotes from the specs
 522
 523 *** MIME multipart: Notion of structured, related body parts
 524   :PROPERTIES:
 525   :Created: [2010-03-25 Do]
 526   :END:
 527
 528   -  [[http://tools.ietf.org/html/rfc2046.html#section-5.1.1][RFC2046, 5.1.1]]
 529
 530 #+BEGIN_QUOTE
 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
 542    are recognized.
 543 #+END_QUOTE
 544 *** MIME multipart: order of entities inside a multipart
 545   :PROPERTIES:
 546   :Created: [2010-03-25 Do]
 547   :END:
 548
 549   - [[http://tools.ietf.org/html/rfc2046.html#section-5.1.3][RFC2046, 5.1.3]]
 550
 551 #+BEGIN_QUOTE
 552 5.1.3.  Mixed Subtype
 553
 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".
 558
 559 #+END_QUOTE
 560
 561   - [[http://tools.ietf.org/html/rfc2046.html#section-5.1.4][RFC2046, 5.1.4]]
 562
 563 #+BEGIN_QUOTE
 564 5.1.4.  Alternative Subtype
 565
 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
 569    information.
 570
 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.
 579 #+END_QUOTE
 580
 581 #+BEGIN_QUOTE
 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.
 591 #+END_QUOTE
 592 * Org mode issue tracking library
 593
 594 A collection of helper functions to maintain the [[file:org-issues.org][Issue file]] from
 595 within Wanderlust and (partly) Gnus.
 596
 597 You can download a current version of this file [[file:code/elisp/org-issue.el][here]].
 598
 599 Currently following commands are provided:
 600
 601   - `org-issue-new' :: File a new issue for current message
 602
 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.
 607
 608   - `org-issue-close' :: Close issue of current message.
 609
 610   - `org-issue-tag'  :: Tag issue of current message.
 611
 612   - `org-issue-update-message-flag' :: Update message flag according
 613        to issue file.
 614
 615        If the issue for current message is closed, the message flag is
 616        removed.
 617
 618   - `org-issue-link-gmane' :: An Org mode web link pointing to current
 619        message on gmane is pushed to killring and clipboard.
 620