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