Add API for generating a bib entry for an nLab page

We add an endpoint, /cite, for providing bib entries for use when
citing an nLab page. One, for citing the current version of the page,
is under /show/, and the other, for a citing a specific revision of a
page, is under /revision/.

We also add an item 'Cite' to the menu at the bottom of the current
version of an nLab page to link to the /cite endpoint under /show; and
similarly add an item 'Cite' to the menu at the bottom of a historical
version of an nLab page to link to the /cite endpoint under /revision.

The endpoints display both an ASCII bib entry (that most likely to be
relevant) and a unicode version. Since nLab page names can be in
unicode, and since there is no generic way to convert unicode to
ASCII, we simply hard-code a conversion for each unicode character
which currently occurs in some nLab page title, with the exception of
a single Chinese entry and a few Russian entries, for which we provide
a romanisation. This hard-coded conversion will need to be kept up to
date.

As with the other APIs added recently, the API itself is written in
Python and compiled to a binary via C, by means of Cython. It is
called from the controller corresponding to the new endpoint.

We also take the opportunity to update some instructions in the README
files for the other Python APIs added recently.

app/controllers/cite_controller.rb

@@ -0,0 +1,67 @@
+class CiteController < ApplicationController
+  layout "default", :except => []
+
+  def cite_current
+    page_name = params["page_name"]
+    if !@web.has_page?(page_name)
+      render(
+        :status => 404,
+        :text => "#{page_name} is not the name of any nLab page",
+        :layout => "/errors/404.rhtml")
+      return
+    end
+    @page_name = page_name
+    page = @wiki.read_page(@web_name, @page_name)
+    @revision_number = page.rev_ids.size
+    @revision_id = page.revisions[@revision_number - 1].id
+    return
+  end
+
+  def cite
+    page_name = params["page_name"]
+    if !@web.has_page?(page_name)
+      render(
+        :status => 404,
+        :text => "#{page_name} is not the name of any nLab page",
+        :layout => "/errors/404.rhtml")
+      return
+    end
+    @page_name = page_name
+    @revision_number = params["revision_number"]
+    page = @wiki.read_page(@web_name, @page_name)
+    @revision_id = page.revisions[Integer(@revision_number) - 1].id
+    return
+  end
+
+  def bib_entry(page_name, revision_number, revision_id, current, unicode)
+    bib_entry_binary = File.join(
+      Rails.root,
+      "script/bib_entry")
+    if unicode
+      if current
+        bib_entry = %x(
+          "#{bib_entry_binary}" "#{page_name}" "#{revision_number}" "#{revision_id}" --current --unicode_permitted)
+      else
+        bib_entry = %x(
+          "#{bib_entry_binary}" "#{page_name}" "#{revision_number}" "#{revision_id}" --unicode_permitted)
+      end
+    else
+      if current
+        bib_entry = %x(
+          "#{bib_entry_binary}" "#{page_name}" "#{revision_number}" "#{revision_id}" --current)
+      else
+        bib_entry = %x(
+          "#{bib_entry_binary}" "#{page_name}" "#{revision_number}" "#{revision_id}")
+      end
+    end
+    return bib_entry
+  end
+
+  helper_method :bib_entry
+
+  def link_to_nlab_page(page_name)
+    "https://ncatlab.org/" + @web_name + "/show/" + URI.encode(page_name)
+  end
+
+  helper_method :link_to_nlab_page
+end

app/views/cite/cite.rhtml

@@ -0,0 +1,21 @@
+<%# coding: utf-8 %>
+<%-
+  @title = "Cite — " + @page_name + " (revision " + @revision_number.to_s + ")"
+  @show_footer = true
+-%>
+
+<div>
+  <h3>Overview</h3>
+  <p>We recommend the following .bib file entries for citing this revision of the page <a style="color: #005c19" href="<%= link_to_nlab_page(@page_name) %>"><%= @page_name %></a>. The first is to be used if one does not have unicode support, which is likely the case if one is using bibtex. The second can be used if one does has unicode support. If there are no non-ascii characters in the page name, then the two entries are the same.</p>
+  <p>In either case, the hyperref package needs to have been imported in one's tex (or sty) file. There are no other dependencies.</p>
+  <p>The author field has been chosen so that the reference appears in the 'alpha' citation style. Feel free to adjust this.</p>
+
+  <h3>Bib entry — Ascii</h3>
+  <p><pre><%= bib_entry(@page_name, @revision_number, @revision_id, false, false) %></pre></p>
+
+  <h3>Bib entry — Unicode</h3>
+  <p><pre><%= bib_entry(@page_name, @revision_number, @revision_id, false, true) %></pre></p>
+
+  <h3>Problems?</h3>
+  <p>Please report any problems with the .bib entries at the <a href="https://nforum.ncatlab.org/">nForum</a>.</p>
+</div>

app/views/cite/cite_current.rhtml

@@ -0,0 +1,21 @@
+<%# coding: utf-8 %>
+<%-
+  @title = "Cite — " + @page_name
+  @show_footer = true
+-%>
+
+<div>
+  <h3>Overview</h3>
+  <p>We recommend the following .bib file entries for citing the current version of the page <a style="color: #005c19" href="<%= link_to_nlab_page(@page_name) %>"><%= @page_name %></a>. The first is to be used if one does not have unicode support, which is likely the case if one is using bibtex. The second can be used if one does has unicode support. If there are no non-ascii characters in the page name, then the two entries are the same.</p>
+  <p>In either case, the hyperref package needs to have been imported in one's tex (or sty) file. There are no other dependencies.</p>
+  <p>The author field has been chosen so that the reference appears in the 'alpha' citation style. Feel free to adjust this.</p>
+
+  <h3>Bib entry — Ascii</h3>
+  <p><pre><%= bib_entry(@page_name, @revision_number, @revision_id, true, false) %></pre></p>
+
+  <h3>Bib entry — Unicode</h3>
+  <p><pre><%= bib_entry(@page_name, @revision_number, @revision_id, true, true) %></pre></p>
+
+  <h3>Problems?</h3>
+  <p>Please report any problems with the .bib entries at the <a href="https://nforum.ncatlab.org/">nForum</a>.</p>
+</div>

app/views/wiki/page.rhtml

@@ -27,7 +27,9 @@
 <div class="navigation navfoot">
 
   <%= raw navigation_menu_for_page.join(' | ') %>
-
+  <%- if @web.name == "nLab" %>
+  | <a href="https://ncatlab.org/nlab/show/<%= h @page.name %>/cite" style="color: black">Cite</a>
+  <%- end %>
   <span class="views">
     | Views:
     <%= link_to('Print',

app/views/wiki/revision.rhtml

@@ -30,6 +30,9 @@
 
 <div class="navigation navfoot">
   <%= raw navigation_menu_for_revision.join(' | ') %>
+  <%- if @web.name == "nLab" %>
+  | <a href="https://ncatlab.org/nlab/revision/<%= h @page.name %>/<%= @revision_number.to_s %>/cite" style="color: black">Cite</a>
+  <%- end %>
     <span class="views">
     | View:
     <%= link_to 'Source', {:web => @web.address, :action => 'source', :id => @page.name, :rev => @revision_number},

config/routes.rb

@@ -29,6 +29,8 @@ def connect_to_web(map, generic_path, generic_routing_options)
   connect_to_web map, ':web/import/:id', :controller => 'file', :action => 'import'
   connect_to_web map, ':web/login', :controller => 'wiki', :action => 'login'
   connect_to_web map, ':web/web_list', :controller => 'wiki', :action => 'web_list'
+  connect_to_web map, ":web/show/:page_name/cite", :controller => "cite", :requirements => { :page_name => /.*/}, :action => "cite_current", :page_name => nil
+  connect_to_web map, ":web/revision/:page_name/:revision_number/cite", :controller => "cite", :requirements => { :page_name => /.*/}, :action => "cite", :page_name => nil, :revision_number => nil
   connect_to_web map, ':web/show/diff/:id', :controller => 'wiki', :action => 'show', :mode => 'diff', :requirements => {:id => id_regexp}
   connect_to_web map, ':web/revision/diff/:id/:rev', :controller => 'wiki', :action => 'revision', :mode => 'diff',
        :requirements => { :rev => /\d+/, :id => id_regexp}

script/src/author_contributions/README.md

@@ -39,11 +39,7 @@ NLAB_DATABASE_PASSWORD
 NLAB_DATABASE_NAME
 NLAB_LOG_DIRECTORY
 
-These should be set in .bash_profile for use when developing, and in
-
-/etc/default/unicorn
-
-for when the script is caled from Instiki.
+Currently these are hardcoded in config/environment_variables.rb (not in git).
 
 Deployment
 ----------

script/src/bib_entry/README.md

@@ -0,0 +1,47 @@
+Development
+-----------
+
+Setup virtual environment (only needs to be done once).
+
+python -m venv venv
+source venv/bin/activate
+pip install --upgrade pip
+pip install mysqlclient
+deactivate
+
+After this, whenever wish to run (note that cannot use ./ syntax):
+
+source venv/bin/activate
+python detect_nforum_discussion.py [params]
+deactivate
+
+Compilation
+-----------
+
+cp bib_entry.py bib_entry.pyx
+
+#The --embed option causes a main() function to be added to the created C file
+cython bib_entry.pyx --embed
+
+#All three of the -I,-L, and -l parameters are needed. The -I parameter
+#adds directory in which Python.h can be found. The -L parameter adds directory
+#where the libpython3.6m.so library can be found. The -l must be the same
+#as the name of the .so file with the 'lib' at the beginning removed.
+gcc -I /usr/include/python3.4m -L /usr/lib64 -l python3.4m bib_entry.c -o bib_entry
+
+Environment variables
+---------------------
+
+The script relies on the following environment variable being set.
+
+NLAB_DATABASE_USER
+NLAB_DATABASE_PASSWORD
+NLAB_DATABASE_NAME
+NLAB_LOG_DIRECTORY
+
+Currently these are hardcoded in config/environment_variables.rb (not in git).
+
+Deployment
+----------
+
+cp bib_entry ~/www/nlab-prod/script/