org-devel.org

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:nil -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc ':t
   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 #+HTML_LINK_UP:    index.html
  12 #+HTML_LINK_HOME:  https://orgmode.org/worg/
  13
  14 # This file is released by its authors and contributors under the GNU
  15 # Free Documentation license v1.3 or later, code examples are released
  16 # under the GNU General Public License v3 or later.
  17
  18 #+LINK: fireforgrepofile http://repo.or.cz/w/org-fireforg.git?a=blob_plain;f=%s;hb=HEAD
  19
  20 # This file is the default header for new Org files in Worg.  Feel free
  21 # to tailor it to your needs.
  22
  23 Some org-mode related project currently being developed in worg.
  24
  25 * Org Collector
  26
  27 #+index: Collector
  28
  29 Located in the =contrib/lisp/= directory of org-mode.
  30
  31 A utility for collecting properties from the headers in an org file,
  32 running the properties through arbitrary elisp functions, and
  33 presenting the results in a table.
  34
  35 The functionality of this tool is similar to the functionality of
  36 [[info:org:Capturing%20column%20view][info:org:Capturing column view]], but this has support for processing
  37 prior to the generation of the table.
  38
  39 Here is a simple example application of this utility.
  40
  41 #+begin_comment ems better example
  42 it might be better to put an exercise example here if someone has one.
  43 #+end_comment
  44
  45 #+BEGIN: propview :id "data" :cols (ITEM f d list (apply '* list) (+ f d))
  46
  47 #+END:
  48
  49 *** Example Data
  50       :PROPERTIES:
  51       :ID:       data
  52       :END:
  53
  54 ****** run1
  55       :PROPERTIES:
  56       :d: 33
  57       :f: 2
  58       :list: '(9 2 3 4 5 6 7)
  59       :END:
  60
  61
  62 ****** run2
  63       :PROPERTIES:
  64       :d: 34
  65       :f: 4
  66       :END:
  67
  68
  69 ****** run3
  70       :PROPERTIES:
  71       :d: 35
  72       :f: 4
  73       :END:
  74
  75
  76 ****** run4
  77       :PROPERTIES:
  78       :d: 36
  79       :f: 2
  80       :END:
  81
  82
  83 * Fireforg, a Firefox extension for org interaction (EXPERIMENTAL)
  84
  85 #+index: Fireforg
  86
  87 Fireforg is a Firefox extension, that interacts with Emacs Org-mode.
  88
  89 For the displayed URL it shows the associated tags in the status bar
  90 and allows to show a list of annotations that can be instantly visited
  91 in Emacs.
  92
  93 Additionally, in every website it marks all links that occur in the agenda files.
  94
  95 For every link in the agenda files the previous heading and its tags
  96 are associated with it.
  97
  98 For *scientific use*, it is possible to *send BibTeX entries* for
  99 sites supported by the Zotero plugin to Emacs. [[*Import%20BibTeX%20using%20Zotero][Additional steps]] are
 100 necessary for this to work.
 101
 102 ** Caveats
 103    :PROPERTIES:
 104    :ID:       13179b21-d70a-4255-a8f1-9f4e4e729074
 105    :END:
 106 The following notes should be taken into consideration before using Fireforg:
 107  - On the Emacs side a registry of all links in the agenda files will
 108    be generated and saved in plain text onto the harddrive.
 109    - The generation can take very a long time depending on the size of
 110      the agenda files and the number of links in them.
 111    - The generated file can become quite large.
 112    - When files are *encrypted* having some information from them in
 113      plain text on the harddrive might not be what you want.
 114  - Firefox will read and look through the registry file for the
 115    currently viewed site. Depending on the size of the registry file
 116    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]]
 117    this might slow down the browsing experience.
 118
 119 ** Installation
 120
 121    - Install org-protocol according to its [[file:org-contrib/org-protocol.org][manual]] and *please verify
 122      that it's working* using either the bookmarks or by invoking it directly in the shell:
 123      : emacsclient 'org-protocol://remember://w/http%3A%2F%2Forgmode.org%2F/Org-Mode%3A%20Your%20Life%20in%20Plain%20Text%20-%20Mozilla%20Firefox/'
 124    - Get org-fireforg.el from [[fireforgrepofile:lisp/org-fireforg.el][here]] and put the following into your
 125      =.emacs= *after* the section that initializes org-protocol:
 126      : (add-to-list 'load-path "~/path/to/org/fireforg/")
 127      : (require 'org-fireforg)
 128      : (org-fireforg-registry-insinuate)
 129
 130      and as the last line of the file:
 131      : (org-fireforg-registry-initialize t)
 132
 133      Note that creating the registry can take a long time depending on
 134      the size of the agenda files and the number of links in them.
 135
 136    - Visit [[fireforgrepofile:build/fireforg.xpi][this link]] with Firefox, confirm installation of the extension and restart.
 137
 138      (Windows users will have to adjust: org-fireforg-registry-file-xml  in Emacs
 139      and "registry-file" in Fireforgs preferences to be the same file.)
 140
 141 *** Installation from a git clone
 142
 143     It is also possible to clone the git repository first, using:
 144     : git clone http://repo.or.cz/r/org-fireforg.git
 145     , install lisp/org-fireforg.el according to the instructions above
 146     and add a file named =fireforg@burtzlaff.de= containing the path
 147     to the "fireforg" subdirectory into =~/.mozilla/firefox/<your
 148     profile>/extensions/=.
 149
 150     In my setup for example there is a file
 151     =~/.mozilla/firefox/4xyx9l73.default/extensions/fireforg@burtzlaff.de=
 152     containing
 153     : /home/andy/projects/org-fireforg/fireforg
 154
 155     A restart of Firefox is required for this to work.
 156
 157 ** Basic usage
 158 *** The status bar entry
 159
 160     If the currently viewed url is found in your agenda files, the number
 161     of occurrences together with all associated tags will be shown in the
 162     status bar. A left click on the status bar entry will show a list of
 163     all headings associated with the currently viewed url. Selecting one
 164     of them lets Emacs visit that heading.
 165
 166     For example, this heading in one of your agenda files:
 167     : * Greatest tool in the world [[https://orgmode.org/][Org mode]]    :Org:
 168     will yield the following when visiting https://orgmode.org/ and left clicking:
 169
 170     [[file:images/screenshots/org-fireforg-screenshot.png]]
 171
 172 *** Triggering store-link and remember
 173     Right clicking on the status bar entry shows a menu that let's you
 174     trigger org-protocol's "store-link" and "remember".
 175
 176     There is an entry for every remember template listed in the [[*List%20of%20characters%20specifying%20available%20remember%20templates][preferences]].
 177
 178     The entries in the submenu "All tabs" will call remember for every tab
 179     in the current window. This option only makes sense if a remember
 180     template is used, that stores the note automatically ("%!" in the template string), e.g.:
 181     : * %:description \n %:link %!
 182
 183 *** Mark links that occur in the agenda files in websites
 184
 185     Whenever a site is loaded, Fireforg will alter the style of all links
 186     in it, that occur in the agenda files. The tooltip of those links is
 187     set to contain the annotations.
 188
 189     This feature can be turned off using an [[*Lookup%20links%20on%20page%20load][option]] in the [[*Preferences][preferences
 190     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
 191     not the tooltip is set]] is also customizable.
 192
 193 *** Context menu for links
 194
 195     The context menu (accessible by right clicking on a link) has a
 196     submenu "Fireforg", where all annotations for that link are listed:
 197
 198     [[file:images/screenshots/org-fireforg-screenshot-context-menu.png]]
 199
 200 ** Import BibTeX using Zotero
 201    :PROPERTIES:
 202    :ID:       e6fc94c6-7fef-4348-b998-f6a6f58eded8
 203    :END:
 204    Fireforg is able to retrieve BibTex entries for the all sites
 205    supported by [[http://www.zotero.org/][Zotero]]. To achieve this the following additional steps
 206    are necessary:
 207    - Install Zotero 1.0.10 from the [[http://www.zotero.org/][Zotero Website]]
 208    - Set "Inject Zotero" in Fireforg's preference dialog
 209      [fn:ffprefdiag: Fireforg's preference dialogue is accessible in
 210      Firefox's menu under Tools->Add-ons->Fireforg->Preferences].
 211
 212      *Warning: On restart a small function is injected into Zotero to
 213      catch imported entries. The change to the code is minimal and
 214      non-permanent. In a worst case scenario Zotero's database might
 215      get corrupted, though that hasn't happened yet.*
 216
 217    - Restart Firefox
 218
 219      Whenever a single entry (*not* a collection) is imported into Zotero -
 220      e.g. by clicking the white "document" symbol that appears to the right
 221      in the url bar if Zotero supports importing the current site - it is
 222      automatically exported to BibTeX and sent to org mode using
 223      org-protocol. In Emacs it is put into the kill ring in a format
 224      depending on the variable =org-fireforg-received-bibtex-format=:
 225
 226    - =nil=: The BibTeX entry is passed directly into the kill ring.
 227    - =heading= (Default): A heading is generated with the BibTeX
 228      fields as properties with prefix "BIB_":
 229      : * [[<link to site>][<Title>]]
 230      :  :PROPERTIES:
 231      :   :CUSTOM_ID: <BibTeX key>
 232      :   :BIB_entryType: <article, ...>
 233      :   :BIB_author: ...
 234      :   :BIB_title: ...
 235      :   ...
 236      :   :END:
 237    - =headingWithPropsAndBibTeXContent=: a heading with properties as
 238      described above is generated and the entry in BibTeX format is
 239      appended.
 240    - =headingWithBibTeXContent=: same as the previous one but without the properties
 241
 242      If the 'url' field is a *static URL*, the link to it will be highlighted
 243      in search results in every search engine. Otherwise the option
 244      [[id:3ab02821-03c4-4fa7-9a3a-e9701245c5d8][Match sites by comparing their DOI with saved bibliography entries]] might help.
 245
 246      To export BibTeX information from all headings in the current buffer
 247      with at least the "BIB_entryType" property call:
 248    - =org-fireforg-export-bibtex-to-file= to export to a file
 249    - =org-fireforg-export-bibtex-to-new-buffer= to export into a new buffer
 250
 251 *** Digital Object Identifiers (DOI)
 252     :PROPERTIES:
 253     :ID:       fbd09ba5-6632-40df-bcc0-8e5a7b9eb7a7
 254     :END:
 255     If a BibTeX entry contains a field 'doi', a URL will be generated by
 256     prepending "http://dx.doi.org/" to the corresponding property
 257     'BIB_doi'. It will be handled as any other URL. There is a
 258     [[id:3ab02821-03c4-4fa7-9a3a-e9701245c5d8][corresponding functionality in the plugin]] that allows to associated
 259     pages despite non-static URLs.
 260 ** Preferences
 261    Fireforg's preference dialogue is accessible in Firefox's menu
 262    under Tools->Add-ons->Fireforg->Preferences
 263 ***** Registry file
 264       The file containing an xml tree with all link-headline associations
 265       generated from the agenda files. You should not need to change
 266       this. It has to be same as the customizable variable
 267       =org-fireforg-registry-file-xml= in Emacs.
 268 ***** Lookup links on page load
 269       :PROPERTIES:
 270       :ID:       e77f15a8-c358-44fd-a207-8c422fee2d1e
 271       :END:
 272       When enabled, all links in a web page that have headlines
 273       associated with them are marked. This is achieve by adding the
 274       following CSS style string to the element:
 275       Depending on the size of the registry this *might slow Firefox down*.
 276 ***** CSS style string for links with annotations
 277       The string that is appended to the CSS =style= string of a link
 278       element, if annotations for it exist.
 279 ***** Overwrite tooltip for links with annotations
 280       If enabled, sets the tooltip for the links, for which
 281       annotations exist to contain those annotations.
 282 ***** Inject Zotero
 283       After restarting Firefox, a function in the Zotero code gets altered
 284       so that all BibtTeX entries (*not* collections) that are imported are
 285       sent using org-protocol and are handled in Emacs according to the
 286       variable =org-fireforg-received-bibtex-format= as described [[* Import BibTeX using Zotero][here]].  Due
 287       to [[* Technical note][design choices in Zotero]] this is a bit fragile and can yield errors
 288       and *might possibly even break Zotero's database*. It is not advisable
 289       to use Zotero for production when enabling this option in Fireforg.
 290 ***** Match sites by comparing their DOI with saved bibliography entries
 291       :PROPERTIES:
 292       :ID:       3ab02821-03c4-4fa7-9a3a-e9701245c5d8
 293       :END:
 294       Extract the Digital Object Identifier (DOI) from a page, prepend
 295       "http://dx.doi.org/" to it and look up the resulting URL.
 296
 297       If using a bibliography format [[id:e6fc94c6-7fef-4348-b998-f6a6f58eded8][with properties]], a [[id:fbd09ba5-6632-40df-bcc0-8e5a7b9eb7a7][URL is
 298       generated in the same way from the value of the field "BIB_doi"
 299       if it exists]]. Thus documents can be matched regardless of the
 300       possibly non-static URL.
 301 ***** Prefetch links to extract DOI
 302       :PROPERTIES:
 303       :ID:       d73476f3-6c09-479c-abea-f33d3e0e074a
 304       :END:
 305       *Prefetch all links in a page* after it is loaded, extract the
 306       DOIs - if any - and [[id:fbd09ba5-6632-40df-bcc0-8e5a7b9eb7a7][use it to find annotations]]. This requires
 307       the option [[id:3ab02821-03c4-4fa7-9a3a-e9701245c5d8][Match sites by comparing their DOI with saved
 308       bibliography entries]] to be set.
 309
 310       A site is only prefetched once in every Firefox session, because the
 311       associated URL mapping is saved until Firefox is restarted.
 312
 313       *All links starting with "http" will be prefetched (except for
 314       files with extensions: PDF, GIF, PNG or SWF).* This option can
 315       also be toggled in the status bar menu.
 316
 317       *This option will generate additional network traffic and might
 318       slow the browsing experience*
 319 ***** List of characters specifying available remember templates
 320       For every character in this list an entry in the [[*Triggering%20store-link%20and%20remember][popup menu]] will
 321       be generated, that triggers remember with the template
 322       associated with the character.
 323 ***** Enable workaround for Mac
 324       see [[* Workaround for the inability to register a protocol in Firefox on the Mac][here]]
 325 ***** Temporary file for Mac workaround
 326       see [[* Workaround for the inability to register a protocol in Firefox on the Mac][here]]
 327
 328 ** Workaround for the inability to register a protocol in Firefox on the Mac
 329
 330    A long known bug in Firefox on the Mac is reported to stop protocol
 331    registration from working. To work around this Fireforg is able to
 332    write the org-protocol urls to a temporary file, that is read every
 333    second and, if non empty, passed to emacsclient and emptied.
 334
 335    To enable this:
 336    - check "Enable workaround for Mac" in Fireforg's preference dialogue [fn:ffprefdiag]
 337    - 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.
 338
 339 ** Updating
 340
 341    To avoid confusion, always update both org-fireforg.el and the plugin.
 342
 343    The plugin has to be uninstalled and then reinstalled as described
 344    above. Automatic updating will be used when the testing phase is over.
 345
 346 ** Bugreporting and discussion
 347
 348    - Discussions go to the org-mode list.
 349    - Bugreports are better not sent to the list, but rather directly to
 350      the [[mailto:andreas%20AT%20burtzlaff%20DOT%20de][author]] (Please add "[Fireforg]" to the subject.).
 351
 352 *** A checklist for bug tracing
 353
 354     To create a test case put:
 355     : * Greatest tool in the world [[https://orgmode.org/][Org mode]]    :Org:
 356     into one of your agenda files and save it.
 357
 358     If problems arise please go through this checklist to locate the problem:
 359
 360     - Does the file "~/.org-fireforg-registry.xml" exist and does it contain "orgmode.org"?
 361     - *No on either*: Send me the last content of the Messages buffer in Emacs
 362     - *Yes*: In the Firefox menu: "Tools"->"Error console" look for
 363       errors containing: "chrome://fireforg/" and send them to me.
 364
 365 ** Technical note
 366
 367    Different instances of Zotero's Translator object seem to share state
 368    in a non-obvious way. This makes coding very fragile and even lets
 369    some imports fail (silently) after Fireforg has injected its code. The
 370    failure when importing collections is somehow related to this.  While
 371    I find it a strange design choice, it is not in my power to change it.
 372 * MEMO org-mail-htmlize: Create MIME messages based on Org
 373
 374 ** Representing a MIME internet message
 375
 376    A MIME internet message consists of one or more MIME entities. Each
 377    MIME entity is of a distinct type and subtype, has a body and
 378    optional MIME headers related to its content.
 379
 380    A MIME entity is represented as a list:
 381
 382    (TYPE SUBTYPE BODY CONT-HEAD)
 383
 384    - TYPE :: Symbol of MIME media type (e.g. text, video, audio).
 385
 386    - SUBTYPE :: Symbol of MIME media subtype (e.g. plain, html).
 387
 388    - BODY :: String with entity body -or- list of other MIME entities.
 389
 390    - CONT-HEAD :: List of cons with content related MIME header
 391                   fields.  The name of the header field without the
 392                   prefix "Content-" is car, the value cdr.
 393
 394    Example:
 395
 396    #+begin_src emacs-lisp
 397    '(text html "<h1>Headline</h1>" ((disposition . inline)))
 398    #+end_src
 399
 400    For messages of type multipart the body consists of a list of one
 401    or more MIME entities.
 402
 403    #+begin_src emacs-lisp
 404      '(multipart alternative
 405                  '((text plain "* Headline")
 406                    (text html "<h1>headline</h1>")))
 407    #+end_src
 408
 409 ** MIME delimiters of SEMI and mml
 410
 411    The MIME delimiters are defined in an association list with a
 412    symbol of the library's name as key and delimiter format strings as
 413    values.  For each library there are three formatstrings.
 414
 415    (SYMBOL DELIM-SINGLE DELIM-SINGLE-CONT DELIM-MULTI)
 416
 417    - DELIM-SINGLE :: Denoting a single MIME entity.
 418
 419                      Strings are passed in this order:
 420
 421                      1. type
 422
 423                      2. subtype
 424
 425                      3. content header
 426
 427                      4. body
 428
 429    - DELIM-SINGLE-CONT :: Format of content header strings.
 430
 431         Strings are passed in this order:
 432
 433         1. header field name
 434
 435         2. header field value
 436
 437    - DELIM-MULTI :: Enclosing parts of a multipart entity.
 438
 439                     Strings are passed in this order:
 440
 441                     1. subtype
 442
 443                     2. body
 444
 445                     3. subtype
 446
 447    #+begin_src emacs-lisp
 448      (setq org-mail-htmlize-mime-delimiter-alist
 449            '((semi "\n--[[%s/%s%s]]\n%s" "\ncontent-%s: %s" "\n--<<%s>>-{\n%s\n--}-<<%s>>")
 450              (mml "\n<#part type=\"%s/%s\"%s>\n%s" " %s=\"%s\"" "\n<#multipart type=\"%s\">\n%s\n<#/multipart>")))
 451    #+end_src
 452
 453 ** Generic function
 454
 455    This generic function returns a string representation with MIME
 456    delimiters depending on the variable =org-mail-htmlize-mime-lib=.
 457
 458    #+begin_src emacs-lisp
 459      (setq org-mail-htmlize-mime-lib 'semi)
 460    #+end_src
 461
 462    #+begin_src emacs-lisp
 463      (defun org-mail-htmlize-mime-entity (type subtype body
 464                                                &optional cont-head)
 465        "Return string representation of MIME entity.
 466
 467      TYPE is the type of entity body.
 468      SUBTYPE is the subtype of body.
 469      BODY is the body of the entity.  Either a string with the body
 470      content or a list with one ore more MIME entities.
 471      Optional argument CONT-HEAD is a list of cons with content
 472      specific headers, name in car and value in cdr."
 473        (let ((delimlst (assoc org-mail-htmlize-mime-lib
 474                               org-mail-htmlize-mime-delimiter-alist)))
 475          (if (eq type 'multipart)
 476              (format (nth 3 delimlst) subtype
 477                      (mapconcat (lambda (b)
 478                                    (apply 'org-mail-htmlize-mime-entity
 479                                           (car b) (cadr b) (cddr b)))
 480                                 body "")
 481                      subtype)
 482            (format (nth 1 delimlst)
 483                    type subtype
 484                    (mapconcat (lambda (h)
 485                                  (format (nth 2 delimlst) (car h) (cdr h)))
 486                               cont-head "")
 487                    body))))
 488    #+end_src
 489
 490 ** Open questions
 491
 492 *** How to handle charset information?
 493
 494 *** How to attach files?
 495
 496     The generic function expects BODY either be a string or a list.
 497     Attaching binary file (image, etc.) requires to encode it so the
 498     message will pass the message system.  So we /might/ use kind of a
 499     encoder (e.g. base64) on our own.
 500
 501     Or, what seems a cleaner solution: Use attachment function of the
 502     respective MIME mode.  To achive this: Introduce third possibility
 503     for BODY: A cons with the filename in car and symbol of the
 504     function in cdr.
 505
 506     (FILENAME . FUNCTION)
 507
 508     #+begin_src emacs-lisp
 509       '(image jpeg ("/path/to/image" . org-mail-htmlize-add-attachment))
 510     #+end_src
 511
 512     The function =org-mail-htmlize-add-attachment= is called with file
 513     name as argument and calls the appropriate function depending on
 514     =org-mail-htmlize-mime-lib= and returns a string
 515
 516        - with the encoded body
 517
 518          -or-
 519
 520        - the complete MIME entity
 521
 522     Side effect: The user might be prompted for attachment settings
 523     (e.g. encoding).  But, on the other hand: We delegate the job of
 524     creating the attachment to the library that is responsible for
 525     mime.
 526
 527 ** Quotes from the specs
 528
 529 *** MIME multipart: Notion of structured, related body parts
 530   :PROPERTIES:
 531   :Created: [2010-03-25 Do]
 532   :END:
 533
 534   - [[http://tools.ietf.org/html/rfc2046.html#section-5.1.1][RFC2046, 5.1.1]]
 535
 536     #+BEGIN_QUOTE
 537        NOTE:  Conspicuously missing from the "multipart" type is a notion of
 538        structured, related body parts. It is recommended that those wishing
 539        to provide more structured or integrated multipart messaging
 540        facilities should define subtypes of multipart that are syntactically
 541        identical but define relationships between the various parts. For
 542        example, subtypes of multipart could be defined that include a
 543        distinguished part which in turn is used to specify the relationships
 544        between the other parts, probably referring to them by their
 545        Content-ID field.  Old implementations will not recognize the new
 546        subtype if this approach is used, but will treat it as
 547        multipart/mixed and will thus be able to show the user the parts that
 548        are recognized.
 549     #+END_QUOTE
 550 *** MIME multipart: order of entities inside a multipart
 551   :PROPERTIES:
 552   :Created: [2010-03-25 Do]
 553   :END:
 554
 555   - [[http://tools.ietf.org/html/rfc2046.html#section-5.1.3][RFC2046, 5.1.3]]
 556
 557     #+BEGIN_QUOTE
 558     5.1.3.  Mixed Subtype
 559
 560        The "mixed" subtype of "multipart" is intended for use when the body
 561        parts are independent and need to be bundled in a particular order.
 562        Any "multipart" subtypes that an implementation does not recognize
 563        must be treated as being of subtype "mixed".
 564
 565     #+END_QUOTE
 566
 567   - [[http://tools.ietf.org/html/rfc2046.html#section-5.1.4][RFC2046, 5.1.4]]
 568
 569     #+BEGIN_QUOTE
 570     5.1.4.  Alternative Subtype
 571
 572        The "multipart/alternative" type is syntactically identical to
 573        "multipart/mixed", but the semantics are different.  In particular,
 574        each of the body parts is an "alternative" version of the same
 575        information.
 576
 577        Systems should recognize that the content of the various parts are
 578        interchangeable.  Systems should choose the "best" type based on the
 579        local environment and references, in some cases even through user
 580        interaction.  As with "multipart/mixed", the order of body parts is
 581        significant.  In this case, the alternatives appear in an order of
 582        increasing faithfulness to the original content.  In general, the
 583        best choice is the LAST part of a type supported by the recipient
 584        system's local environment.
 585     #+END_QUOTE
 586
 587     #+BEGIN_QUOTE
 588        In general, user agents that compose "multipart/alternative" entities
 589        must place the body parts in increasing order of preference, that is,
 590        with the preferred format last.  For fancy text, the sending user
 591        agent should put the plainest format first and the richest format
 592        last.  Receiving user agents should pick and display the last format
 593        they are capable of displaying.  In the case where one of the
 594        alternatives is itself of type "multipart" and contains unrecognized
 595        sub-parts, the user agent may choose either to show that alternative,
 596        an earlier alternative, or both.
 597     #+END_QUOTE
 598 * Org mode issue tracking library
 599
 600 A collection of helper functions to maintain the [[file:org-issues.org][Issue file]] from within
 601 Wanderlust and (partly) Gnus.
 602
 603 You can download a current version of this file [[file:code/elisp/org-issue.el][here]].
 604
 605 Currently following commands are provided:
 606
 607   - 'org-issue-new' :: File a new issue for current message
 608
 609        Creates a new TODO in 'org-issue-issue-file' below the headline
 610        "New Issues" with keyword NEW.  If customization variable
 611        'org-issue-message-flag' is non-nil and flagging messages is
 612        supported, the message of this issue is flagged.
 613
 614   - 'org-issue-close' :: Close issue of current message.
 615
 616   - 'org-issue-tag'  :: Tag issue of current message.
 617
 618   - 'org-issue-update-message-flag' :: Update message flag according
 619        to issue file.
 620
 621        If the issue for current message is closed, the message flag is
 622        removed.
 623
 624   - 'org-issue-link-gmane' :: An Org mode web link pointing to current
 625        message on gmane is pushed to killring and clipboard.
 626