UP | HOME

Support via Liberapay

Fireforg, a Firefox extension for org interaction (EXPERIMENTAL)

Note: The development of org-fireforg has ceased back in 2009

Fireforg is a Firefox extension, that interacts with Emacs Org-mode.

For the displayed URL it shows the associated tags in the status bar and allows to show a list of annotations that can be instantly visited in Emacs.

Additionally, in every website it marks all links that occur in the agenda files.

For every link in the agenda files the previous heading and its tags are associated with it.

For scientific use, it is possible to send BibTeX entries for sites supported by the Zotero plugin to Emacs. Additional steps are necessary for this to work.

Caveats

The following notes should be taken into consideration before using Fireforg:

  • On the Emacs side a registry of all links in the agenda files will be generated and saved in plain text onto the harddrive.
    • The generation can take very a long time depending on the size of the agenda files and the number of links in them.
    • The generated file can become quite large.
    • When files are encrypted having some information from them in plain text on the harddrive might not be what you want.
  • Firefox will read and look through the registry file for the currently viewed site. Depending on the size of the registry file and on the options Lookup links on page load and Prefetch links to extract DOI this might slow down the browsing experience.

Installation

  • Install org-protocol according to its manual and please verify that it’s working using either the bookmarks or by invoking it directly in the shell:

    emacsclient 'org-protocol://remember://w/http%3A%2F%2Forgmode.org%2F/Org-Mode%3A%20Your%20Life%20in%20Plain%20Text%20-%20Mozilla%20Firefox/'
    
  • Get fireforgrepofile:lisp/org-fireforg.el and put the following into your .emacs after the section that initializes org-protocol:

    (add-to-list 'load-path "~/path/to/org/fireforg/")
    (require 'org-fireforg)
    (org-fireforg-registry-insinuate)
    

    and as the last line of the file:

    (org-fireforg-registry-initialize t)
    

    Note that creating the registry can take a long time depending on the size of the agenda files and the number of links in them.

  • Visit fireforgrepofile:build/fireforg.xpi with Firefox, confirm installation of the extension and restart.

    (Windows users will have to adjust: org-fireforg-registry-file-xml in Emacs and “registry-file” in Fireforgs preferences to be the same file.)

Installation from a git clone

note: development seems to have ceased back in 2009. Use with caution.

It is also possible to clone the git repository first, using:

git clone https://repo.or.cz/w/org-fireforg.git

, install lisp/org-fireforg.el according to the instructions above and add a file named fireforg@burtzlaff.de containing the path to the “fireforg” subdirectory into ~/.mozilla/firefox/<your profile>/extensions/.

In my setup for example there is a file ~/.mozilla/firefox/4xyx9l73.default/extensions/fireforg@burtzlaff.de containing

/home/andy/projects/org-fireforg/fireforg

A restart of Firefox is required for this to work.

Basic usage

The status bar entry

If the currently viewed url is found in your agenda files, the number of occurrences together with all associated tags will be shown in the status bar. A left click on the status bar entry will show a list of all headings associated with the currently viewed url. Selecting one of them lets Emacs visit that heading.

For example, this heading in one of your agenda files:

* Greatest tool in the world [[https://orgmode.org/][Org mode]]    :Org:

will yield the following when visiting https://orgmode.org/ and left clicking:

org-fireforg-screenshot.png

Triggering store-link and remember

Right clicking on the status bar entry shows a menu that let’s you trigger org-protocol’s “store-link” and “remember”.

There is an entry for every remember template listed in the preferences.

The entries in the submenu “All tabs” will call remember for every tab in the current window. This option only makes sense if a remember template is used, that stores the note automatically (“%!” in the template string), e.g.:

* %:description \n %:link %!

Mark links that occur in the agenda files in websites

Whenever a site is loaded, Fireforg will alter the style of all links in it, that occur in the agenda files. The tooltip of those links is set to contain the annotations.

This feature can be turned off using an option in the preferences dialog. The CSS-style used for marking the link and whether or not the tooltip is set is also customizable.

Context menu for links

The context menu (accessible by right clicking on a link) has a submenu “Fireforg”, where all annotations for that link are listed:

org-fireforg-screenshot-context-menu.png

Import BibTeX using Zotero

Fireforg is able to retrieve BibTex entries for the all sites supported by Zotero. To achieve this the following additional steps are necessary:

  • Install Zotero 1.0.10 from the Zotero Website
  • Set “Inject Zotero” in Fireforg’s preference dialog 1.

    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.

  • Restart Firefox

    Whenever a single entry (not a collection) is imported into Zotero - e.g. by clicking the white “document” symbol that appears to the right in the url bar if Zotero supports importing the current site - it is automatically exported to BibTeX and sent to org mode using org-protocol. In Emacs it is put into the kill ring in a format depending on the variable org-fireforg-received-bibtex-format:

  • nil: The BibTeX entry is passed directly into the kill ring.
  • heading (Default): A heading is generated with the BibTeX fields as properties with prefix “BIB_”:

    * [[<link to site>][<Title>]]
     :PROPERTIES:
      :CUSTOM_ID: <BibTeX key>
      :BIB_entryType: <article, ...>
      :BIB_author: ...
      :BIB_title: ...
      ...
      :END:
    
  • headingWithPropsAndBibTeXContent: a heading with properties as described above is generated and the entry in BibTeX format is appended.
  • headingWithBibTeXContent: same as the previous one but without the properties

    If the ’url’ field is a static URL, the link to it will be highlighted in search results in every search engine. Otherwise the option Match sites by comparing their DOI with saved bibliography entries might help.

    To export BibTeX information from all headings in the current buffer with at least the “BIB_entryType” property call:

  • org-fireforg-export-bibtex-to-file to export to a file
  • org-fireforg-export-bibtex-to-new-buffer to export into a new buffer

Digital Object Identifiers (DOI)

If a BibTeX entry contains a field ’doi’, a URL will be generated by prepending “http://dx.doi.org/” to the corresponding property ’BIB_doi’. It will be handled as any other URL. There is a corresponding functionality in the plugin that allows to associated pages despite non-static URLs.

Preferences

Fireforg’s preference dialogue is accessible in Firefox’s menu under Tools->Add-ons->Fireforg->Preferences

Workaround for the inability to register a protocol in Firefox on the Mac

A long known bug in Firefox on the Mac is reported to stop protocol registration from working. To work around this Fireforg is able to write the org-protocol urls to a temporary file, that is read every second and, if non empty, passed to emacsclient and emptied.

To enable this:

Updating

To avoid confusion, always update both org-fireforg.el and the plugin.

The plugin has to be uninstalled and then reinstalled as described above. Automatic updating will be used when the testing phase is over.

Bugreporting and discussion

  • Discussions go to the org-mode list.
  • Bugreports are better not sent to the list, but rather directly to the author (Please add “[Fireforg]” to the subject.).

A checklist for bug tracing

To create a test case put:

* Greatest tool in the world [[https://orgmode.org/][Org mode]]    :Org:

into one of your agenda files and save it.

If problems arise please go through this checklist to locate the problem:

  • Does the file “~/.org-fireforg-registry.xml” exist and does it contain “orgmode.org”?
  • No on either: Send me the last content of the Messages buffer in Emacs
  • Yes: In the Firefox menu: “Tools”->“Error console” look for errors containing: “chrome://fireforg/” and send them to me.

Technical note

Different instances of Zotero’s Translator object seem to share state in a non-obvious way. This makes coding very fragile and even lets some imports fail (silently) after Fireforg has injected its code. The failure when importing collections is somehow related to this. While I find it a strange design choice, it is not in my power to change it.

Footnotes:

1

Fireforg’s preference dialogue is accessible in Firefox’s menu under Tools->Add-ons->Fireforg->Preferences

Documentation from the orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.