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:      bzg AT altern 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.