org-devel.org

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -: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 * Current Projects
  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
  82 *** Status
  83 Fireforg is still experimental and the installation is not hassle free. But it's worth it :-)
  84
  85 *** Installation
  86
  87 - Install org-protocol according to its [[file:org-contrib/org-protocol.org][manual]] and verify that it's working using the bookmarks.
  88 - Get org-fireforg.el from [[fireforgrepofile:lisp/org-fireforg.el][here]] and put the following into your =.emacs=:
  89     : (add-to-list 'load-path "~/path/to/org/fireforg/")
  90     : (require 'org-fireforg)
  91     : (org-fireforg-registry-insinuate)
  92   and as the last line of the file:
  93     : (org-fireforg-registry-initialize t)
  94
  95 - Visit [[fireforgrepofile:build/fireforg.xpi][this]] with Firefox, confirm installation of the extension and restart.
  96
  97 (Windows users will have to adjust: org-fireforg-registry-file-xml  in Emacs
  98 and "registry-file" in Fireforgs preferences to be the same file.)
  99
 100 *** Usage
 101
 102 **** The status bar entry
 103
 104 If the currently viewed url is found in your agenda files, the number
 105 of occurrences together with all associated tags will be shown in the
 106 status bar. A left click on the status bar entry will show a list of
 107 all headings associated with the currently viewed url. Selecting one
 108 of them lets emacs visit that heading.
 109
 110 For example, this heading in one of your agenda files:
 111    : * Greatest tool in the world [[http://orgmode.org/][Org mode]]    :Org:
 112 will yield the following when visiting http://orgmode.org/ and left clicking:
 113
 114 [[file:images/screenshots/org-fireforg-screenshot.png]]
 115
 116 Right clicking on the status bar entry shows a menu that let's you
 117 trigger org-protocol's "store-link" and "remember" (for customization see [[* Preferences]]).
 118
 119 **** Mark links that occur in the agenda files in websites
 120
 121 Whenever a site is loaded, Fireforg will alter the style of all links
 122 in it, that occur in the agenda files. The tooltip of those links is
 123 set to contain the annotations.
 124
 125 This feature can be turned off in
 126 "Tools->Add-Ons->Fireforg->Preferences->Lookup links on page load".
 127 The CSS-style used for the marking is customizable through "CSS style
 128 string for links with annotations" in the preferences.
 129 Changing the tooltip can be turned off by unchecking "Overwrite tooltip for links with annotations".
 130
 131 **** Context menu for links
 132
 133 The context menu (accessible by right clicking on a link) has a
 134 submenu "Fireforg", where all annotations for that link are listed:
 135 [[file:images/screenshots/org-fireforg-screenshot-context-menu.png]]
 136
 137 *** Import BibTeX using Zotero
 138 Fireforg is able to retrieve BibTex entries for the all sites supported by [[http://www.zotero.org/][Zotero]]. To achieve this the following additional steps are necessary:
 139 - Install Zotero 1.0.10 from the [[http://www.zotero.org/][Zotero Website]]
 140 - Set "Inject Zotero" in Fireforg's preference dialog [fn:ffprefdiag:  Fireforg's preference dialogue is accessible in Firefox's menu under Tools->Add-ons->Fireforg->Preferences].
 141
 142   *Warning: On restart a small function is injected into Zotero to catch imported entries. The change to the code is minimal and non-permanent. In a worst case scenario Zotero's database might get corrupted, though that hasn't happened yet.*
 143
 144 - Restart Firefox
 145
 146 Whenever a single entry (*not* a collection) is imported into Zotero -
 147 e.g. by clicking the white "document" symbol that appears to the right
 148 in the url bar if Zotero supports importing the current site - it is
 149 automatically exported to BibTeX and sent to org mode using
 150 org-protocol. In Emacs it is put into the kill ring in a format
 151 depending on the variable =org-fireforg-received-bibtex-format=:
 152
 153 - =nil=: The BibTeX entry is passed directly into the kill ring.
 154 - =heading= (Default): A heading is generated with the BibTeX fields as properties with prefix "BIB_":
 155   : * [[<link to site>][<Title>]]
 156   :  :PROPERTIES:
 157   :   :CUSTOM_ID: <BibTeX key>
 158   :   :BIB_entryType: <article, ...>
 159   :   :BIB_author: ...
 160   :   :BIB_title: ...
 161   :   ...
 162   :   :END:
 163 - =headingWithPropsAndBibTeXContent=: a heading with properties as described above is generated and the entry in BibTeX format is appended.
 164 - =headingWithBibTeXContent=: same as the previous one but without the properties
 165
 166 If the url field is a static url, the link to it will be highlighted in search
 167 results in every search engine.
 168
 169 To export BibTeX information from all headings in the current buffer
 170 with at least the "BIB\_entryType" property call:
 171 - =org-fireforg-export-bibtex-to-file= to export to a file
 172 - =org-fireforg-export-bibtex-to-new-buffer= to export into a new buffer
 173 *** Preferences
 174  Fireforg's preference dialogue is accessible in Firefox's menu under Tools->Add-ons->Fireforg->Preferences
 175 **** Registry file
 176 The file containing an xml tree with all link-headline associations
 177 generated from the agenda files. You should not need to change
 178 this. It has to be same as the customizable variable
 179 =org-fireforg-registry-file-xml= in Emacs.
 180 **** Lookup links on page load
 181 When enabled, all links in a web page that have headlines associated
 182 with them are marked. This is achieve by adding the following CSS style string to the element:
 183 **** CSS style string for links with annotations
 184 The string that is appended to the CSS =style= string of a link
 185 element, if annotations for it exist.
 186 **** Overwrite tooltip for links with annotations
 187 If enabled, sets the tooltip for the links, for which annotations exist to contain those annotations.
 188 **** Inject Zotero
 189 After restarting Firefox, a function in the Zotero code gets altered
 190 so that all BibtTeX entries (*not* collections) that are imported are
 191 sent using org-protocol and are handled in Emacs according to the
 192 variable =org-fireforg-received-bibtex-format= as described [[* Import BibTeX using Zotero][here]].  Due
 193 to [[* Technical note][design choices in Zotero]] this is a bit fragile and can yield errors
 194 and *might possibly even break Zotero's database*. It is not advisable
 195 to use Zotero for production when enabling this option in Fireforg.
 196 **** Use remember template
 197 The character indicating which remember template to use.
 198 **** Enable workaround for Mac
 199 see [[* Workaround for the inability to register a protocol in Firefox on the Mac][here]]
 200 **** Temporary file for Mac workaround
 201 see [[* Workaround for the inability to register a protocol in Firefox on the Mac][here]]
 202
 203 *** Workaround for the inability to register a protocol in Firefox on the Mac
 204
 205 A long known bug in Mac Firefox is reported to stop protocol
 206 registration from working. To work around this Fireforg is able to
 207 write the org-protocol urls to a temporary file, that is read every
 208 second and, if non empty, passed to emacsclient and emptied.
 209
 210 To enable this:
 211 - check "Enable workaround for Mac" in Fireforg's preference dialogue [fn:ffprefdiag]
 212 - 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.
 213
 214 *** Updating
 215
 216 To avoid confusion, always update both org-fireforg.el and the plugin.
 217
 218 The plugin has to be uninstalled and then reinstalled as described
 219 above. Automatic updating will be used when the testing phase is over.
 220
 221 *** Bugreporting and discussion
 222
 223 - Discussions go to the org-mode list.
 224 - Bugreports are better not sent to the list, but rather directly to
 225   the [[mailto:andreas%20AT%20burtzlaff%20DOT%20de][author]] (Please add "[Fireforg]" to the subject.), because there are probably too many, yet.
 226
 227 **** A checklist for bug tracing
 228
 229 To create a test case put:
 230    : * Greatest tool in the world [[http://orgmode.org/][Org mode]]    :Org:
 231 into one of your agenda files and save it.
 232
 233 If problems arise please go through this checklist to locate the problem:
 234
 235 - Does the file "~/.org-fireforg-registry.xml" exist and does it contain "orgmode.org"?
 236  - *No on either*: Send me the last content of the Messages buffer in Emacs
 237  - *Yes*: In the Firefox menu: "Tools"->"Error console" look for errors containing: "chrome://fireforg/" and send them to me.
 238
 239 *** Technical note
 240
 241 Different instances of Zotero's Translator object seem to share state
 242 in a non-obvious way. This makes coding very fragile and even lets
 243 some imports fail (silently) after Fireforg has injected its code. The
 244 failure when importing collections is somehow related to this.  While
 245 I find it a strange design choice, it is not in my power to change it.