< Back to Colloids.org

Coding an entire website with only a few dozen lines of code

Markdown: the basic text markup language

Take a look at the raw markdown source for the pages on this website, which are more informative than stepping through a lot of examples explictly. By comparing the raw markdown with the final generated html and webpage, it is clear how compact and efficient writing in markdown can be. Each post page starts with several lines delimited by three dashes; this is the yaml header, which gives configuration options, discussed later. Everything that is translated into material that appears on the generated webpages.

Github-flavored Markdown

There is a standard version of Markdown, but Github has chosen a slightly extended version of the language with a few more formatting commands, and slightly different behavior. This dialect must be specified in the options for the Markdown converter in order for the text to be interpreted properly.

Jekyll: Building a website

Ruby and its installed option are configured by Gemfile in the root directory of the site, which is really short in this case (just make the file and everything works; there is nothing else that needs to address this):

source 'https://rubygems.org'
gem 'github-pages'

Jekyll’s configuration options are held in a configuration file, config.yml:

markdown: kramdown
kramdown:
   input: GFM
   default_lang: python

This specifies the software package Kramdown as the program (used by Github) that converts Markdown to html5 with CSS formatting, using the templates. Kramdown is configured to use the extended style conventions in Github-flavored Markdown, abbreviated GFM, and the default language for codeblocks, but at least at present, this doesn’t really affect things as presented by Github. Kramdown takes the posts in the _posts subdirectory, and converts them to html. The posts themselves cannot determine their placement and indexing, which is controlled by other files and integrated by Kramdown.

index.html

The site’s main index.html is quite brief:

---
layout: master
title: Colloid Physics on the International Space Station
---
<header class="container page-header">

  <div class="wrapper"><a class="site-title" rel="author" href="http://peterlu.org/"><img id="logo_header" src="/assets/images/logo_header.png" alt="Peter J. Lu"/></a>
  </div>
</header>



<article>
  <h1>BCAT and ACE: Colloid Physics in Space</h1>
  <ul class="posts">
    
      <li><span>05 Sep 2014</span>: <a href="/science/operations/2014/09/05/slow_phase_sep.html">Significant science, slower phase separation in ACE than in BCAT-KP</a></li>
    
      <li><span>26 Aug 2014</span>: <a href="/science/operations/2014/08/26/same_sample.html">Same sample, different behavior?</a></li>
    
      <li><span>22 Aug 2014</span>: <a href="/science/operations/2014/08/22/gelation_phase_sep.html">Significant science, gelation and phase separation</a></li>
    
      <li><span>21 Aug 2014</span>: <a href="/science/operations/2014/08/21/stabilize_images.html">Image stabilization and filtering</a></li>
    
      <li><span>18 Aug 2014</span>: <a href="/operations/2014/08/18/lamp_problems.html">On-orbit challenges, broken LMM lamp</a></li>
    
      <li><span>03 Aug 2014</span>: <a href="/informatics/2014/08/03/markdown_latex_pdf.html">Converting the website to documents</a></li>
    
      <li><span>02 Aug 2014</span>: <a href="/informatics/2014/08/02/markdown_html.html">Building a website from a few dozen lines of code</a></li>
    
      <li><span>01 Aug 2014</span>: <a href="/informatics/2014/08/01/linux_latex.html">Collaborative writing with Linux, LaTeX, Eclipse and git</a></li>
    
      <li><span>27 Jul 2014</span>: <a href="/science/operations/2014/07/27/preparing_data.html">First look at some raw data, preliminary stabilization</a></li>
    
      <li><span>15 Jul 2014</span>: <a href="/operations/science/2014/07/15/whereis_data.html">Why is it taking so long to post data? Data organization</a></li>
    
      <li><span>14 Jul 2014</span>: <a href="/science/operations/2014/07/14/ace_m2_run4_inital.html">ACE-M2 run 4, first phase-separation images</a></li>
    
      <li><span>02 Jul 2014</span>: <a href="/science/operations/2014/07/02/ace_m2_first_round_success.html">ACE-M2 runs 1 and 2 success summary</a></li>
    
      <li><span>01 Jul 2014</span>: <a href="/operations/2014/07/01/ace_m2_ops.html">ACE-M2 first-run flight operations</a></li>
    
      <li><span>17 Jun 2014</span>: <a href="/science/operations/2014/06/17/ace_m3_samples.html">ACE M3 samples for quantitative microscopy</a></li>
    
      <li><span>04 Jun 2014</span>: <a href="/operations/science/2014/06/04/ace_first_data.html">First images of ACE-M2 samples</a></li>
    
      <li><span>04 Jun 2014</span>: <a href="/operations/2014/06/04/ace_first_ops.html">ACE-M2 starting operations</a></li>
    
      <li><span>29 May 2014</span>: <a href="/policy/2014/05/29/onion.html">Life imitates The Onion</a></li>
    
      <li><span>18 Apr 2014</span>: <a href="/operations/2014/04/18/spacex3_launch.html">ACE-M2 launched into space</a></li>
    
      <li><span>06 Mar 2014</span>: <a href="/science/operations/2014/03/06/ace_m2_sample_layout.html">ACE-M2 sample layout</a></li>
    
      <li><span>05 Mar 2014</span>: <a href="/science/2014/03/05/ace_m2_samples.html">Samples for the second ACE experiment, ACE-M2</a></li>
    
      <li><span>01 Jan 2014</span>: <a href="/policy/informatics/2014/01/01/start.html">Telling the story of science on the Space Station</a></li>
    
  </ul>
</article> 

<footer class="container">  
<div class="column">
    <p>
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-nc-sa/4.0/80x15.png" /></a><br />This work by <a xmlns:cc="http://creativecommons.org/ns#" href="http://www.colloids.org" property="cc:attributionName" rel="cc:attributionURL">Peter J. Lu</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.
</p>
</div>
</footer>

The yaml header describes which layout to use, in this case a master layout that has the core html for each page on the site. This allows consistent formatting of pages throughout the site, using the concept of templates (specifically, Liquid Templates) for this purpose.

<!DOCTYPE html>
<html>
  <head>
    <title>Peter J. Lu - Building a website from a few dozen lines of code </title>
    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
    <link href='http://fonts.googleapis.com/css?family=Source+Sans+Pro' rel='stylesheet' type='text/css'>
    <link rel="stylesheet" href="/css/master.css" type="text/css" media="screen" charset="utf-8"/>
  </head>

  <body>
      <div id='content'>
        <div class="row"><a href="/colloidsorg/">&lt; Back<span class="in-iframe-hide"> to Colloids.org</span></a></div>
<article>
<h1 id="open-source-free-tools-for-writing-collaboration-and-publishing">Open-source, free tools for writing, collaboration and publishing</h1>

<p>As we are starting to have some interesting results, it’s the right time to think about the science, and how to communicate it. As I mentioned at the outset, this site is a bit of an experiment itself in being open from start to finish. That philosophy extends to the tools that we use throughout the process, favoring those that are open-source and can therefore be distributed, re-used, and modified at will.</p>

<p>Using these free tools is partly philosophical, in terms of supporting the freedom to create and use content. But a large part is also practical; I work in a very heterogeneous computing environment, with multiple flavors of UNIX (Linux, Solaris / Illumos) plus Windows (and many working with me use Mac). Standardizing on closed tools means picking a single or small handful of vendors, none of which support all of the platforms I am using every day. Because open-source software can be modified, it can be fixed to run on a large number of different kinds of computers, which is critical toward actually getting real work done.</p>

<p>Free software can often leave the user a bit spoiled for choice. That is, sometimes there really are ten ways to do the same thing, and it’s hard to know what’s best. So what I am summarizing here is but <em>one</em> way to pick good tools to generate research publications in asynchronous collaboration with researchers spread all over the world. I have tried to select those tools which are generally useful and have a large user base, so that the time invested in a particular package won’t disappear because either the software is no longer maintained and updated to reflect new technologies and operating systems; or (in the case of closed software), the manufacturer goes out of business or decides to change something fundamental.</p>

<p>Thus I am giving a set of step-by-step instructions, starting with an absolutely empty / blank computer, and putting all of the tools on that we actually use to write, distribute, submit and publish actual papers in scientific journals.</p>

<h2 id="linux">Linux</h2>

<p>Most open-source tools are designed to work with Linux first and foremost, usually with reasonable Mac OS X support (though none of this is tested on that platform). Windows support is generally less developed, and frankly instead of using the Windows-Linux hybrid tools, it’s much easier to just install VirtualBox and run everything in an Linux virtual machine.</p>

<h3 id="linux-mint-17-qiana-xfce-edition">Linux Mint 17 Qiana, XFCE edition</h3>

<p>Based on Ubuntu 14.04 LTS, but with fewer kernel updates; XFCE desktop is fast, easy to use, and widespread. Either bare-metal install or virtual machine (e.g. VirtualBox) is fine for this demo.</p>

<ol>
  <li>Download <code class="highlighter-rouge">.iso</code> or <code class="highlighter-rouge">.usb</code> from &lt;www.linuxmint.com/download.php&gt;</li>
  <li>Make bootable DVD / USB stick; in Linux, use the program called <code class="highlighter-rouge">Startup Disk Creator</code>.</li>
  <li>Run updates and restart.</li>
</ol>

<h3 id="synaptic-package-manager">Synaptic package manager</h3>

<p>In <strong>Synaptic Package Manager</strong> (<code class="highlighter-rouge">apt-get</code>), install packages:</p>

<ul>
  <li><code class="highlighter-rouge">git</code></li>
  <li><code class="highlighter-rouge">pcmanfm</code></li>
  <li><code class="highlighter-rouge">alacarte</code></li>
</ul>

<h2 id="latex">LaTeX</h2>

<p>Everyone should use LaTeX for all scientific and technical publications. It is the default / native format for most good scientific journals, and can be converted directly from other text markup languages, allowing the distribution of the same content through multiple channels.</p>

<h3 id="texlive-2014">TexLive 2014</h3>

<p>This is a large, modern, updated and full-featured distribution, with a great deal of flexibility. Although you can install it through Synaptic, for some reason the packages that Ubuntu releases are always way, way out of date. Instead:</p>

<ol>
  <li>Download the latest from <a href="http://tug.org/texlive/">http://tug.org/texlive/</a></li>
  <li>Extract the archive, either using the desktop or command-line.</li>
  <li>Run the installation script with root permissions:</li>
</ol>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo ./install_tl
</code></pre></div></div>

<p>This launches the text-based installer. A good minimum installation (about 700 MB) uses the <code class="highlighter-rouge">scheme-basic</code> scheme, letter size instead of A4, and adds the following packages:</p>

<ul>
  <li>recommended fonts</li>
  <li>Latex recommended packages</li>
</ul>

<p><em>For Asian names</em>:</p>
<ul>
  <li>Chinese</li>
  <li>Chinese/Japanese/Korean (base)</li>
</ul>

<p>The installer will download all of the packages you specify, so you must be online, and depending on the server traffic, can be very slow.</p>

<ol>
  <li>After installation completes, add the RevTeX-4.1 packages for <em>Physical Review</em> journals.</li>
</ol>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>/usr/local/texlive/2014/bin/x86_64-linux $ sudo ./tlmgr install revtex
</code></pre></div></div>

<h2 id="eclipse">Eclipse</h2>

<p>Eclipse is a large software integrated development environment (IDE), open-sourced by IBM. Current version is Eclipse 4.4 “Luna”. To install:</p>

<ol>
  <li>download from <a href="http://eclipse.org/downloads/">http://eclipse.org/downloads/</a></li>
  <li>extract archive, which places all files in single folder</li>
  <li>for convenience, move to a system directory</li>
</ol>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo mv eclipse /opt/
sudo chmod 777 /opt/eclipse
</code></pre></div></div>

<h3 id="texlipse">Texlipse</h3>

<p>LaTeX integration for Eclipse, which controls the document build process. When you modify any file and save it, Eclipse will automatically execute the right programs to rebuild the document. To install in Eclipse:</p>

<ol>
  <li>
    <p><code class="highlighter-rouge">help-&gt;install</code> new software, with path <a href="http://texlipse.sourceforge.net">http://texlipse.sourceforge.net</a></p>
  </li>
  <li>
    <p><code class="highlighter-rouge">Window-&gt;Preferences-&gt;Texlipse-&gt;Builder Settings</code>, set path: <code class="highlighter-rouge">/usr/local/texlive/2014/bin/x86_64-linux</code></p>
  </li>
</ol>

<h2 id="git">Git</h2>

<p>Git is the version-control system used to manage the Linux kernel, and was written by Linux Torvalds himself (the creator of Linux).</p>

<h3 id="configure-git-for-first-usage">Configure git for first usage</h3>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git config --global user.name "Peter J. Lu"
git config --global user.email plu@fas.harvard.edu
</code></pre></div></div>

<h3 id="ssh-keys">SSH keys</h3>
<p>In order to manage identities and security, git (like many modern Linux tools) requires authentication, and does so via SSH keys. This will allow modifications from your machine to change a remote repository in the cloud, and replaces login credentials. To generate the SSH keys to allow you to <code class="highlighter-rouge">push</code> to remote git repository:</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ssh-keygen -t rsa -C "plu@fas.harvard.edu"
</code></pre></div></div>

<p>You will be prompted for a passphrase, the password that you will use to unlock this key every time you want to use it.</p>

<h3 id="add-ssh-key-to-bitbucketorg-repository">Add SSH key to bitbucket.org repository</h3>

<ol>
  <li>login to <a href="http://www.bitbucket.org">http://www.bitbucket.org</a></li>
  <li>In upper right corner, drop down <code class="highlighter-rouge">manage account</code>, SSH keys option on left: add text from id_rsa.pub</li>
</ol>

<h2 id="working-with-git-eclipse-and-latex">Working with Git, Eclipse and LaTeX</h2>

<p>The first step is to clone a repository from the remote location to the local machine and then import into a new Eclipse project. In the workspace directory (typically <code class="highlighter-rouge">~/workspace</code>):</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone git@bitbucket.org:peterjlu/aot_xl.git
</code></pre></div></div>

<p>In Eclipse: <code class="highlighter-rouge">file-&gt;import-&gt;general-&gt;existing projects into workspace</code></p>

<p>This will create a new project that Eclipse is aware has a remote git-repository. Eclipse has great integration with git, so that you can use either the command-line or the internal GUI-based tools, with the same results and no conflicts.</p>

<h3 id="updating-a-git-repository-command-line">Updating a git repository: command-line</h3>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git add -A
git commit -m 'name of update'
git push
</code></pre></div></div>

<p>You will be prompted for the passphrase; once you enter it successfully, it automatically uploads and updates the remote repository. To confirm this, you can check online at <a href="http://www.bitbucket.org">http://www.bitbucket.org</a>.</p>

<h3 id="updating-a-git-repository-inside-eclipse">Updating a git repository: inside Eclipse</h3>

<p>Right click on the project name in the <code class="highlighter-rouge">Project Explorer</code>, <code class="highlighter-rouge">Team-&gt;commit</code>. Enter the text that describes the update (the equivalent of the text entered with the command-line <code class="highlighter-rouge">git commit</code>), then press the <code class="highlighter-rouge">Commit and Push</code> button to do the commit and upload in one step.</p>

<h2 id="jabref">JabRef</h2>

<p>LaTeX has a simple, elegant way to store reference data, using text files to store data, which are then processed by a program called BibTeX. BibTeX is installed as part of any normal LaTeX distribution, TeXLive included, and will automatically be called at the appropriate time by Texlipse when building in Eclipse. Hence, there is no special installation procedure.</p>

<p>BibTeX stores references as records in a simple text file, which makes management of the files a bit cumbersome when more than a few references are involved. A number of free tools exist to help with this problem, and one of the more popular ones is JabRef, which works with the native BibTeX text files as the fundamental database format.</p>

<p>JabRef is a java-based program, so there are several ways to run it, either from the command-line as a local java program, or directly from the browser.</p>

<h3 id="install-and-run-jabref-locally">Install and run JabRef locally</h3>

<ol>
  <li>Download the latest version from <a href="http://jabref.sourceforge.net">http://jabref.sourceforge.net</a></li>
  <li>From the command-line, run:</li>
</ol>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>java -jar JabRef-2.10.jar
</code></pre></div></div>

<p>This should run automatically. For information on the version of Java installed, run <code class="highlighter-rouge">java -version</code>, and if that doesn’t work, check the directory <code class="highlighter-rouge">/usr/bin/java</code> to see if the program is installed. Otherwise, use Synaptic to install it.</p>

<h3 id="launch-jabref-from-the-web-browser">Launch JabRef from the web browser</h3>

<p>From <a href="http://jabref.sourceforge.net">http://jabref.sourceforge.net</a>, click the button marked “Web Start, run JabRef instantly”, which will then start the (second most recent) version. You <em>must</em> give the application full access to your machine in order for it to work.</p>

<p>Once launched and a BibTeX file is opened, you get a list of all of the records, which can then be edited by double-clicking. There are several tabs that then open up, so you can either edit the appropriate <code class="highlighter-rouge">Required Fields</code>, or get the direct text listing in the tab marked <code class="highlighter-rouge">BibTeX source</code>.</p>

<h3 id="importing-references-via-the-doi-number-isbn-keywords-etc">Importing references via the DOI number, ISBN, keywords etc.</h3>

<p>What is truly useful about JabRef is the ability to auto-import complete references from various sources:</p>

<ol>
  <li>Click on <code class="highlighter-rouge">Search-&gt;Web</code> search to bring up a new tab on the left,</li>
  <li>There is a drop-down box marked <code class="highlighter-rouge">ACM Portal</code>. Clicking on this brings up a list of sources from which to import data. Select <code class="highlighter-rouge">DOI to BibTeX</code>.</li>
  <li>From a paper, web page, etc. type or paste the DOI number into the white box, and press Fetch. That brings up a new dialog with the paper, which you then click to import. Do the same thing for ISBN number or other search information.</li>
</ol>

<p>This automatically adds a completed reference to the list, but usually requires some modification:</p>

<ol>
  <li>
    <p>Change the <code class="highlighter-rouge">Bibtexkey</code> to whatever key system you use for the rest of your references.</p>
  </li>
  <li>
    <p>The page numbers have a funny character (an en dash) instead of a hyphen; replace this with a regular <code class="highlighter-rouge">-</code> hyphen.</p>
  </li>
</ol>

<p>Save the database / BibTeX file. Now when you add that key in a <code class="highlighter-rouge">~\cite{}</code> command in your LaTeX document, and then save it, Eclipse will build all of the relevant files and generate a document with the updated reference.</p>

</article>


      </div>
  </body>
</html>

This specifies that each page uses html5, and gives the fonts and location of the CSS stylesheet, which is very simple, standard CSS for the site in its present form. The header and footer are stored as separate files in the _includes directory.

The header includes the banner and its link:

<header>
  <a href="http://www.peterlu.org">
    <img src="/images/peterlu_org_banner.png" />
  </a>
</header>

The footer includes the Creative Commons license:

<footer>
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-nc-sa/4.0/80x15.png" /></a><br />This work by <a xmlns:cc="http://creativecommons.org/ns#" href="http://www.colloids.org" property="cc:attributionName" rel="cc:attributionURL">Peter J. Lu</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.
</footer>

The code has a number of double braces, which allow some amount of control in programming, to insert various bits of small data from the original source files.

Post files

Each markdown post has a yaml header that specifies using the post template:

---
layout: master
---
<header class="container page-header">

  <div class="wrapper"><a class="site-title" rel="author" href="http://peterlu.org/"><img id="logo_header" src="/assets/images/logo_header.png" alt="Peter J. Lu"/></a>
  </div>
</header>



<article>
<div class="row"><a href="/colloidsorg/">&lt; Back<span class="in-iframe-hide"> to Colloids.org</span></a></div>
<article>
<h1 id="open-source-free-tools-for-writing-collaboration-and-publishing">Open-source, free tools for writing, collaboration and publishing</h1>

<p>As we are starting to have some interesting results, it’s the right time to think about the science, and how to communicate it. As I mentioned at the outset, this site is a bit of an experiment itself in being open from start to finish. That philosophy extends to the tools that we use throughout the process, favoring those that are open-source and can therefore be distributed, re-used, and modified at will.</p>

<p>Using these free tools is partly philosophical, in terms of supporting the freedom to create and use content. But a large part is also practical; I work in a very heterogeneous computing environment, with multiple flavors of UNIX (Linux, Solaris / Illumos) plus Windows (and many working with me use Mac). Standardizing on closed tools means picking a single or small handful of vendors, none of which support all of the platforms I am using every day. Because open-source software can be modified, it can be fixed to run on a large number of different kinds of computers, which is critical toward actually getting real work done.</p>

<p>Free software can often leave the user a bit spoiled for choice. That is, sometimes there really are ten ways to do the same thing, and it’s hard to know what’s best. So what I am summarizing here is but <em>one</em> way to pick good tools to generate research publications in asynchronous collaboration with researchers spread all over the world. I have tried to select those tools which are generally useful and have a large user base, so that the time invested in a particular package won’t disappear because either the software is no longer maintained and updated to reflect new technologies and operating systems; or (in the case of closed software), the manufacturer goes out of business or decides to change something fundamental.</p>

<p>Thus I am giving a set of step-by-step instructions, starting with an absolutely empty / blank computer, and putting all of the tools on that we actually use to write, distribute, submit and publish actual papers in scientific journals.</p>

<h2 id="linux">Linux</h2>

<p>Most open-source tools are designed to work with Linux first and foremost, usually with reasonable Mac OS X support (though none of this is tested on that platform). Windows support is generally less developed, and frankly instead of using the Windows-Linux hybrid tools, it’s much easier to just install VirtualBox and run everything in an Linux virtual machine.</p>

<h3 id="linux-mint-17-qiana-xfce-edition">Linux Mint 17 Qiana, XFCE edition</h3>

<p>Based on Ubuntu 14.04 LTS, but with fewer kernel updates; XFCE desktop is fast, easy to use, and widespread. Either bare-metal install or virtual machine (e.g. VirtualBox) is fine for this demo.</p>

<ol>
  <li>Download <code class="highlighter-rouge">.iso</code> or <code class="highlighter-rouge">.usb</code> from &lt;www.linuxmint.com/download.php&gt;</li>
  <li>Make bootable DVD / USB stick; in Linux, use the program called <code class="highlighter-rouge">Startup Disk Creator</code>.</li>
  <li>Run updates and restart.</li>
</ol>

<h3 id="synaptic-package-manager">Synaptic package manager</h3>

<p>In <strong>Synaptic Package Manager</strong> (<code class="highlighter-rouge">apt-get</code>), install packages:</p>

<ul>
  <li><code class="highlighter-rouge">git</code></li>
  <li><code class="highlighter-rouge">pcmanfm</code></li>
  <li><code class="highlighter-rouge">alacarte</code></li>
</ul>

<h2 id="latex">LaTeX</h2>

<p>Everyone should use LaTeX for all scientific and technical publications. It is the default / native format for most good scientific journals, and can be converted directly from other text markup languages, allowing the distribution of the same content through multiple channels.</p>

<h3 id="texlive-2014">TexLive 2014</h3>

<p>This is a large, modern, updated and full-featured distribution, with a great deal of flexibility. Although you can install it through Synaptic, for some reason the packages that Ubuntu releases are always way, way out of date. Instead:</p>

<ol>
  <li>Download the latest from <a href="http://tug.org/texlive/">http://tug.org/texlive/</a></li>
  <li>Extract the archive, either using the desktop or command-line.</li>
  <li>Run the installation script with root permissions:</li>
</ol>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo ./install_tl
</code></pre></div></div>

<p>This launches the text-based installer. A good minimum installation (about 700 MB) uses the <code class="highlighter-rouge">scheme-basic</code> scheme, letter size instead of A4, and adds the following packages:</p>

<ul>
  <li>recommended fonts</li>
  <li>Latex recommended packages</li>
</ul>

<p><em>For Asian names</em>:</p>
<ul>
  <li>Chinese</li>
  <li>Chinese/Japanese/Korean (base)</li>
</ul>

<p>The installer will download all of the packages you specify, so you must be online, and depending on the server traffic, can be very slow.</p>

<ol>
  <li>After installation completes, add the RevTeX-4.1 packages for <em>Physical Review</em> journals.</li>
</ol>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>/usr/local/texlive/2014/bin/x86_64-linux $ sudo ./tlmgr install revtex
</code></pre></div></div>

<h2 id="eclipse">Eclipse</h2>

<p>Eclipse is a large software integrated development environment (IDE), open-sourced by IBM. Current version is Eclipse 4.4 “Luna”. To install:</p>

<ol>
  <li>download from <a href="http://eclipse.org/downloads/">http://eclipse.org/downloads/</a></li>
  <li>extract archive, which places all files in single folder</li>
  <li>for convenience, move to a system directory</li>
</ol>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo mv eclipse /opt/
sudo chmod 777 /opt/eclipse
</code></pre></div></div>

<h3 id="texlipse">Texlipse</h3>

<p>LaTeX integration for Eclipse, which controls the document build process. When you modify any file and save it, Eclipse will automatically execute the right programs to rebuild the document. To install in Eclipse:</p>

<ol>
  <li>
    <p><code class="highlighter-rouge">help-&gt;install</code> new software, with path <a href="http://texlipse.sourceforge.net">http://texlipse.sourceforge.net</a></p>
  </li>
  <li>
    <p><code class="highlighter-rouge">Window-&gt;Preferences-&gt;Texlipse-&gt;Builder Settings</code>, set path: <code class="highlighter-rouge">/usr/local/texlive/2014/bin/x86_64-linux</code></p>
  </li>
</ol>

<h2 id="git">Git</h2>

<p>Git is the version-control system used to manage the Linux kernel, and was written by Linux Torvalds himself (the creator of Linux).</p>

<h3 id="configure-git-for-first-usage">Configure git for first usage</h3>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git config --global user.name "Peter J. Lu"
git config --global user.email plu@fas.harvard.edu
</code></pre></div></div>

<h3 id="ssh-keys">SSH keys</h3>
<p>In order to manage identities and security, git (like many modern Linux tools) requires authentication, and does so via SSH keys. This will allow modifications from your machine to change a remote repository in the cloud, and replaces login credentials. To generate the SSH keys to allow you to <code class="highlighter-rouge">push</code> to remote git repository:</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ssh-keygen -t rsa -C "plu@fas.harvard.edu"
</code></pre></div></div>

<p>You will be prompted for a passphrase, the password that you will use to unlock this key every time you want to use it.</p>

<h3 id="add-ssh-key-to-bitbucketorg-repository">Add SSH key to bitbucket.org repository</h3>

<ol>
  <li>login to <a href="http://www.bitbucket.org">http://www.bitbucket.org</a></li>
  <li>In upper right corner, drop down <code class="highlighter-rouge">manage account</code>, SSH keys option on left: add text from id_rsa.pub</li>
</ol>

<h2 id="working-with-git-eclipse-and-latex">Working with Git, Eclipse and LaTeX</h2>

<p>The first step is to clone a repository from the remote location to the local machine and then import into a new Eclipse project. In the workspace directory (typically <code class="highlighter-rouge">~/workspace</code>):</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone git@bitbucket.org:peterjlu/aot_xl.git
</code></pre></div></div>

<p>In Eclipse: <code class="highlighter-rouge">file-&gt;import-&gt;general-&gt;existing projects into workspace</code></p>

<p>This will create a new project that Eclipse is aware has a remote git-repository. Eclipse has great integration with git, so that you can use either the command-line or the internal GUI-based tools, with the same results and no conflicts.</p>

<h3 id="updating-a-git-repository-command-line">Updating a git repository: command-line</h3>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git add -A
git commit -m 'name of update'
git push
</code></pre></div></div>

<p>You will be prompted for the passphrase; once you enter it successfully, it automatically uploads and updates the remote repository. To confirm this, you can check online at <a href="http://www.bitbucket.org">http://www.bitbucket.org</a>.</p>

<h3 id="updating-a-git-repository-inside-eclipse">Updating a git repository: inside Eclipse</h3>

<p>Right click on the project name in the <code class="highlighter-rouge">Project Explorer</code>, <code class="highlighter-rouge">Team-&gt;commit</code>. Enter the text that describes the update (the equivalent of the text entered with the command-line <code class="highlighter-rouge">git commit</code>), then press the <code class="highlighter-rouge">Commit and Push</code> button to do the commit and upload in one step.</p>

<h2 id="jabref">JabRef</h2>

<p>LaTeX has a simple, elegant way to store reference data, using text files to store data, which are then processed by a program called BibTeX. BibTeX is installed as part of any normal LaTeX distribution, TeXLive included, and will automatically be called at the appropriate time by Texlipse when building in Eclipse. Hence, there is no special installation procedure.</p>

<p>BibTeX stores references as records in a simple text file, which makes management of the files a bit cumbersome when more than a few references are involved. A number of free tools exist to help with this problem, and one of the more popular ones is JabRef, which works with the native BibTeX text files as the fundamental database format.</p>

<p>JabRef is a java-based program, so there are several ways to run it, either from the command-line as a local java program, or directly from the browser.</p>

<h3 id="install-and-run-jabref-locally">Install and run JabRef locally</h3>

<ol>
  <li>Download the latest version from <a href="http://jabref.sourceforge.net">http://jabref.sourceforge.net</a></li>
  <li>From the command-line, run:</li>
</ol>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>java -jar JabRef-2.10.jar
</code></pre></div></div>

<p>This should run automatically. For information on the version of Java installed, run <code class="highlighter-rouge">java -version</code>, and if that doesn’t work, check the directory <code class="highlighter-rouge">/usr/bin/java</code> to see if the program is installed. Otherwise, use Synaptic to install it.</p>

<h3 id="launch-jabref-from-the-web-browser">Launch JabRef from the web browser</h3>

<p>From <a href="http://jabref.sourceforge.net">http://jabref.sourceforge.net</a>, click the button marked “Web Start, run JabRef instantly”, which will then start the (second most recent) version. You <em>must</em> give the application full access to your machine in order for it to work.</p>

<p>Once launched and a BibTeX file is opened, you get a list of all of the records, which can then be edited by double-clicking. There are several tabs that then open up, so you can either edit the appropriate <code class="highlighter-rouge">Required Fields</code>, or get the direct text listing in the tab marked <code class="highlighter-rouge">BibTeX source</code>.</p>

<h3 id="importing-references-via-the-doi-number-isbn-keywords-etc">Importing references via the DOI number, ISBN, keywords etc.</h3>

<p>What is truly useful about JabRef is the ability to auto-import complete references from various sources:</p>

<ol>
  <li>Click on <code class="highlighter-rouge">Search-&gt;Web</code> search to bring up a new tab on the left,</li>
  <li>There is a drop-down box marked <code class="highlighter-rouge">ACM Portal</code>. Clicking on this brings up a list of sources from which to import data. Select <code class="highlighter-rouge">DOI to BibTeX</code>.</li>
  <li>From a paper, web page, etc. type or paste the DOI number into the white box, and press Fetch. That brings up a new dialog with the paper, which you then click to import. Do the same thing for ISBN number or other search information.</li>
</ol>

<p>This automatically adds a completed reference to the list, but usually requires some modification:</p>

<ol>
  <li>
    <p>Change the <code class="highlighter-rouge">Bibtexkey</code> to whatever key system you use for the rest of your references.</p>
  </li>
  <li>
    <p>The page numbers have a funny character (an en dash) instead of a hyphen; replace this with a regular <code class="highlighter-rouge">-</code> hyphen.</p>
  </li>
</ol>

<p>Save the database / BibTeX file. Now when you add that key in a <code class="highlighter-rouge">~\cite{}</code> command in your LaTeX document, and then save it, Eclipse will build all of the relevant files and generate a document with the updated reference.</p>

</article>


</article>

<footer class="container">  
<div class="column">
    <p>
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-nc-sa/4.0/80x15.png" /></a><br />This work by <a xmlns:cc="http://creativecommons.org/ns#" href="http://www.colloids.org" property="cc:attributionName" rel="cc:attributionURL">Peter J. Lu</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.
</p>
</div>
</footer>

Once again, the same headers and footers are used, with the main body specified by the word content inside the double braces. The magic of Jekyll as a static site generator is that it knows to put the contents of the converted markdown there, and preserve all of the rest of the formatting consistently for all pages.

Publishing the website

The beautiful thing about this form us static site generator usage is that once the configuration files are set just once, they don’t really have to be changed. All of the time spent is therefore focused on content generation, and testing.

Running Jekyll locally to test the site

As this website is hosted on http://www.github.com/peterlu/peterlu.github.io, it’s easily cloned into a new repository:

git clone git@github.com:peterlu/peterlu.github.io.git

Installing Jekyll locally (assuming the system is in the state at the end of the previous post on Linux and Latex is relatively straightforward:

sudo apt-get install ruby ruby-dev nodejs
sudo gem install bundle

In the main directory, that contains the ‘Gemfile’:

bundle install
bundle update

Then to build the website, and serve it using the built-in webserver:

bundle exec jekyll serve

If this is the only website on the machine being worked on, or all of the settings of all of the websites are the same, the simpler command will suffice:

jekyll serve

Git repository on Github

Once the pages are working fine locally, they need to be pushed to the repository on http://www.github.com. Since we are not managing this in Eclipse, though in principle that would work and might have some advantages, it’s easy as before to do this from the command line.

  1. Stage any modified files that have changed:
git add -A
  1. Verify the files are the correct ones that have been modified:
git status

Sometimes extra temporary files get added, that are not supposed to be committed to the repository, and the status check will show these.

  1. Commit the change
git commit -m 'description of the commit'
  1. Finally, push the commits to the remote repository (which usually will prompt you for a password):
git push

This causes the hosted webpage to re-run Jekyll, and regenerate the entire website. When next loading the page, it should be updated with the latest committed changes.