TeXnical DetailsA personal and development blog about TeX and related technologies.
http://www.seanallred.com/
Mon, 21 Sep 2015 04:27:11 +0000Mon, 21 Sep 2015 04:27:11 +0000Jekyll v2.4.0Reviews<p>The review infrastructure is now live! Why not <a href="/reviews">poke around</a>?</p>
Sat, 11 Jul 2015 17:35:20 +0000http://www.seanallred.com/admin/2015/07/11/reviews.html
http://www.seanallred.com/admin/2015/07/11/reviews.htmladminExsheets<p>Content coming soon. This page is here for infrastructure testing.</p>
Fri, 10 Jul 2015 00:00:00 +0000http://www.seanallred.com/reviews/2015/07/10/exsheets.html
http://www.seanallred.com/reviews/2015/07/10/exsheets.htmlreviewsArara<p>Arara is a <a href="/tex/2015/05/25/tex-terminology.html">build tool</a> designed for TeX documents. Unlike
most other build tools, arara will only do what you tell it to do. It
is exceptionally simple to use, predictable, reliable, and extensible.
You can integrate it with most LaTeX editors out there – instructions
for doing so are clearly spelled out in its excellent manual.</p>
<p>Instead of trying guessing the next compilation step from the log,
arara works by reading ‘directives’ at the top of your file. These
directives tell arara what to do with defaults and options configured
in corresponding ‘rules’. For example, this directive (the line
beginning with <code>% arara:</code>) will call the <code>pdflatex</code> <em>rule</em> with the
defaults, which will in turn call the <code>pdflatex</code> <em>program</em> as
appropriate.</p>
<div class="highlight"><pre><code class="language-tex" data-lang="tex"><span class="c">% arara: pdflatex</span>
<span class="k">\documentclass</span><span class="nb">{</span>article<span class="nb">}</span>
<span class="k">\begin</span><span class="nb">{</span>document<span class="nb">}</span>
hello, world
<span class="k">\end</span><span class="nb">{</span>document<span class="nb">}</span></code></pre></div>
<p>Specifying options for the directive is easy:</p>
<div class="highlight"><pre><code class="language-tex" data-lang="tex"><span class="c">% arara: pdflatex: { synctex: yes }</span>
<span class="k">\documentclass</span><span class="nb">{</span>article<span class="nb">}</span>
<span class="k">\begin</span><span class="nb">{</span>document<span class="nb">}</span>
hello, world
<span class="k">\end</span><span class="nb">{</span>document<span class="nb">}</span></code></pre></div>
<p>The above will add the appropriate command-line options to generate
files for SyncTeX.</p>
<p>The greatest advantage of arara comes in its extensibility. Since
other tools focus on fully automating the process from start to
finish, adding a ‘new step’ involves complex programming to understand
TeX’s output and decide to run that new step. With arara, you can
just create a new rule.</p>
<blockquote>
<p>Since arara is coming out with a new version soon, I will wait for
the release of that new version before adding an example rule. More
content will also follow that release – it’s filled with fantastic
and useful new features :)</p>
</blockquote>
Fri, 10 Jul 2015 00:00:00 +0000http://www.seanallred.com/reviews/2015/07/10/arara.html
http://www.seanallred.com/reviews/2015/07/10/arara.htmlreviewsLaTeX3 and expl3<p>I’ve seen a few people here and there refer to LaTeX3 and <code>expl3</code>
interchangeably. While they’re very related, they are distinct from
each other.</p>
<!--more-->
<dl>
<dt><code>expl3</code></dt>
<dd>The <a href="http://chat.stackexchange.com/transcript/41?m=20892461#20892461">format-independent</a> programming layer powering LaTeX3.
Provides tools to make programming in a TeX environment saner. Under
development, maintained, and stable.</dd>
<dt>LaTeX3</dt>
<dd>The new format of LaTeX, successor to LaTeX2e. Under development
and not yet released.</dd>
</dl>
<p><code>expl3</code> is ready for primetime, but LaTeX3 is not. That said, many
<em>ideas</em> from LaTeX3 are available for use in a <em>status quo</em> referred
to as ‘LaTeX3 in 2e’. Packages like <code>xparse</code>, <code>l3keys2e</code>, and
<code>xtemplate</code> provide an idea of what working in LaTeX3 is going to feel
like.</p>
<p>It’s important to note that the general format of</p>
<div class="highlight"><pre><code class="language-latex" data-lang="latex"><span class="k">\documentclass</span><span class="nb">{</span>&lt;who knows?&gt;<span class="nb">}</span>
<span class="k">\begin</span><span class="nb">{</span>document<span class="nb">}</span>
hello, <span class="k">\emph</span><span class="nb">{</span>world<span class="nb">}</span>
<span class="k">\end</span><span class="nb">{</span>document<span class="nb">}</span></code></pre></div>
<p>is not likely to change (lest the project fail to be adopted). While
the top-level input syntax hasn’t really been nailed down, I suspect
most of the changes will be scoped to the programming and
document-design levels.</p>
<p>Happy TeXing!</p>
Sun, 14 Jun 2015 04:00:00 +0000http://www.seanallred.com/latex3/2015/06/14/expl3-vs-l3.html
http://www.seanallred.com/latex3/2015/06/14/expl3-vs-l3.htmllatex3Who's Who in the World of TeX<p>TeX is a great piece of software with a traditionally specific set of
users: mathematicians, physicists, and computer scientists in the
field all at least know what TeX is simply because it is so pervasive
in that domain. TeX is a fantastic tool for their job and mentors
will commonly teach their students how to use the tool to get the job
done. However, newcomers to TeX are rarely – if ever – given a good
education on all the different players – what goes into getting them
from introduction to installation to a finished product. I hope this
article will answer some of these questions you never knew you had.</p>
<!--more-->
<p>From the simple to the sublime, we will cover the different aspects of
what goes into a working TeX system. This should give you a pretty
complete picture of this brave, new world you’ve entered into.</p>
<ul id="markdown-toc">
<li><a href="#engines">Engines</a></li>
<li><a href="#formats">Formats</a></li>
<li><a href="#extensions">Extensions</a></li>
<li><a href="#editors">Editors</a></li>
<li><a href="#helper-tools">Helper Tools</a></li>
<li><a href="#build-tools">Build tools</a></li>
<li><a href="#distributions">Distributions</a></li>
<li><a href="#ctan">CTAN</a></li>
<li><a href="#conclusion">Conclusion</a></li>
<li><a href="#footnotes">Footnotes</a></li>
</ul>
<h1 id="engines">Engines</h1>
<p>Let’s start with the absolute basics. A TeX engine is a compiled
program. In that sense, it is just like most of the other programs
installed on your computer. This is the program that ultimately
produces your finished document: in most cases, the PDF that you print
or otherwise submit. This program understands only the most basic
instructions related to macros and typesetting – in the lingo, these
are called ‘primitives’. All documents you write will eventually boil
down to these primitives to be understood and processed (or
‘compiled’) by a TeX engine. (It is of consequence to this article
that all TeX engines are programmable – perhaps not strictly by
choice.<sup id="fnref:6"><a href="#fn:6" class="footnote">1</a></sup>)</p>
<p>There are many engines out there beyond Knuth’s original TeX:</p>
<ul>
<li>ε-TeX (upon which most modern engines are based)</li>
<li>pdfTeX</li>
<li>LuaTeX</li>
<li>XeTeX</li>
<li>…</li>
</ul>
<p>Each of these engines understands all of the original primitives in
addition to those related to whichever extra features they may
provide.</p>
<h1 id="formats">Formats</h1>
<p>Next up, we have formats – comprehensive programs written with TeX
primitives to provide an expressive and effective user interface to
TeX primitives. There are
<a href="http://ctan.org/tex-archive/macros">many formats out there today</a>:</p>
<ul>
<li>Plain TeX (or just ‘Plain’)</li>
<li>LaTeX</li>
<li>ConTeXt</li>
<li>…and many others.</li>
</ul>
<p>Since <em>nobody</em> wants to be writing things like,</p>
<div class="highlight"><pre><code class="language-tex" data-lang="tex"><span class="nb">{</span><span class="k">\fam</span> <span class="k">\char</span>&quot;4 select font cmti10<span class="k">\relax</span> italic text<span class="nb">}</span></code></pre></div>
<p>TeX formats provide more meaningful ways to say the same thing:</p>
<ul>
<li><code>{\it italic text\/}</code> (Plain, ConTeXt)</li>
<li><code>\textit{italic text}</code> (LaTeX)</li>
<li>…</li>
</ul>
<p>These are called ‘macros’. Because TeX is programmable, these macros
can become arbitrarily complex – expressing higher-level concepts
like emphasis, sectioning, … even complex graphics and higher-order
mathematics.</p>
<p>Formats define much of the syntax you use to write your document:</p>
<div class="highlight"><pre><code class="language-latex" data-lang="latex"><span class="k">\documentclass</span><span class="nb">{</span>article<span class="nb">}</span>
<span class="k">\begin</span><span class="nb">{</span>document<span class="nb">}</span>
Hello, <span class="k">\textit</span><span class="nb">{</span>world!<span class="nb">}</span>
<span class="k">\end</span><span class="nb">{</span>document<span class="nb">}</span></code></pre></div>
<p>In this example, <code>\documentclass</code>, <code>\begin</code>, <code>\textit</code>, and <code>\end</code> are
macros provided by LaTeX.</p>
<h1 id="extensions">Extensions</h1>
<p>Since the community using TeX is much more diverse and specialized
than any one team can hope to accommodate, the major formats define a
syntax for using extensions that anyone can write and share (licenses
permitting, of course). They provide additional macros that are
relevant to a given task or problem.</p>
<p>Depending on the format, there are different ways to use these
extensions and different names they go by. In LaTeX, they’re called
packages. In ConTeXt, they’re called modules. These are mostly
arbitrary labels – in the end, they’re all plain-text files written
in TeX primitives or whatever additional support the respective format
provides.</p>
<p>Since the formats try to be as widely-applicable as they can, you
likely have seen specialized packages and modules in heavy use for
your particular application:</p>
<ul>
<li><code>\input</code> (Plain)</li>
<li><code>\usepackage</code> (LaTeX)</li>
<li><code>\usemodule</code> (ConTeXt)</li>
</ul>
<p>They represent one of the most distinctive features of TeX systems and
their applicability to an impossibly diverse range of use-cases.
There are thousands upon thousands of these extensions available
online.</p>
<h1 id="editors">Editors</h1>
<p>So far, we’ve only discussed what goes into your document itself as
you write it and what exactly is producing the finished product.
Naturally, we need a way to use this information and actually write
the document.<sup id="fnref:1"><a href="#fn:1" class="footnote">2</a></sup> Of course, as TeX uses plain-text files, you can use
whatever editor you wish, but it would be foolish not to use an editor
that has some level of support for writing a TeX document.<sup id="fnref:7"><a href="#fn:7" class="footnote">3</a></sup></p>
<p>Some popular editors include,<sup id="fnref:2"><a href="#fn:2" class="footnote">4</a></sup></p>
<ul>
<li>TeXworks</li>
<li>TexMaker</li>
<li>TeXstudio</li>
<li>TeXShop</li>
<li>TeXnicCenter</li>
<li>…and many, <em>many</em> others.</li>
</ul>
<p>The programmer’s editors (emacs and vi) also have first-class
environments for writing with TeX – in most cases above and beyond
that of any other editor, specialized or not. However, I will save
that discussion for another post.</p>
<h1 id="helper-tools">Helper Tools</h1>
<p>While TeX can theoretically do anything and everything you want it to
do all on its own, that idea should usually stop at ‘theory’.<sup id="fnref:3"><a href="#fn:3" class="footnote">5</a></sup>
There are many programs that are designed to work with TeX systems
(and indeed, they’re easier to create since TeX files are plain-text).
Here are just a few:</p>
<ul>
<li>The BibTeX format (and the <code>bibtex</code> program) provide a solid
foundation for style-agnostic bibliographies.</li>
<li>The BibLaTeX format (and the <code>biber</code> program) is a re-write of
BibTeX (and <code>bibtex</code>) to allow much more powerful and versatile
citation management than its predecessor. It also has native
support for international languages.</li>
<li><code>makeindex</code> automates indexing, a painful process for anyone who’s
ever had to do so by hand.</li>
<li><code>excel2latex</code> converts simple Excel spreadsheets into LaTeX
tables.</li>
<li><code>latexdiff</code> determines and mark up significant differences
between LaTeX files.</li>
<li><code>latex-git-log</code> generates LaTeX code to typeset version history
information.</li>
</ul>
<p>The list goes on and on. For interested parties, there is a
<a href="http://ctan.org/tex-archive/support">dedicated page</a> for such tools. If you’re a developer,
you should also look into generic text-based templating engines like
Liquid, XSLT, Velocity, <em>etc.</em></p>
<h1 id="build-tools">Build tools</h1>
<p>Since TeX is a command-line tool at its core, most related tools also
use the command-line as the ‘official’ interface. Most (if not all)
specialized editors allow you to run these commands with a menu item
or keyboard shortcut instead of opening up a command prompt and typing
everything by hand. However, there are many TeX-specific build tools
that will automatic this process and can be integrated into your
editor if you wish:<sup id="fnref:4"><a href="#fn:4" class="footnote">6</a></sup></p>
<ul>
<li><code>arara</code> uses ‘directives’ within a TeX source file itself to
record how it should be compiled.<sup id="fnref:5"><a href="#fn:5" class="footnote">7</a></sup></li>
<li><code>latexmk</code> uses some clever heuristics to determine what the next
phases of compilation is.</li>
<li><a href="https://launchpad.net/rubber/"><code>rubber</code></a>, with its clever, hard-to-search name, is another
<code>latexmk</code>-like program.</li>
</ul>
<p>Of course, since these things <em>are</em> command-line based, classic
automation tools like <code>make</code> and other types of generic
build-management tools are available for use, too.</p>
<h1 id="distributions">Distributions</h1>
<p>As you’ve learned, there are many things going on in the world of TeX,
certainly much more than a complete beginner would think even after
using TeX. That’s because large bundles of software and files called
‘distributions’ make downloading and installing a TeX system as easy
as apple pie. Popular distributions include,</p>
<ul>
<li>TeX Live, TUG’s own cross-platform distribution</li>
<li>MiKTeX, a Windows-only distribution</li>
<li>MacTeX, a Mac-only distribution based on TeX Live</li>
<li>proTeXt, a Windows-only distribution based on MiKTeX</li>
</ul>
<p>All of these come with all the engines, formats, packages, and tools
you’re likely to use when working with TeX.
<code>xelatex</code>? Included.
<code>amsmath.sty</code>? Included.
<code>arara</code>? Included.
Distributions are what you download to get started with TeX and
friends.</p>
<p>A note for Linux users: TeX Live is available from the package
repositories, but it is highly suggested you install from upstream.
TeX is a very hard thing to ‘chop up’ for package repositories and
it’s amazing anything can work at all, but the process is fraught with
issues. It is much easier (and in the long run, more efficient) to
simply download the entire TeX Live distribution from TUG’s website.
Installation on Windows might’ve been tricky ten years ago, but I can
vouch that it is seamless at the time of writing.</p>
<h1 id="ctan">CTAN</h1>
<p>In the end, distributions get their files from CTAN, the Comprehensive
TeX Archive Network. Distributions don’t carry <em>everything</em> CTAN has
for practical/licensing reasons, but a huge chunk of it is included.
(A standard distribution is currently around 4.5 GB.) CTAN makes sure
all of these files are always available by managing a network of
mirrors, or copies, that contain the entire corpus of CTAN’s
materials. If something is related to TeX, you will likely find it
there. Packages, package documentation, tools, formats, and engines
are all hosted by CTAN’s generous mirrors.</p>
<p>Any files that are not available on CTAN were not uploaded by their
authors. CTAN can’t make anyone upload anything, so a bit of
Google-searching on the side won’t hurt anyone.</p>
<h1 id="conclusion">Conclusion</h1>
<p>While distinct from one another, each of these areas is highly
dependent on the others for their success. Without CTAN, it’s likely
nobody would ever find TeX on their own. Without LaTeX, TeX may well
have failed in the long run. Without TeX, <code>arara</code> would have no
reason to exist. Without editors, well, you get the idea. I wrote
this article to express that these are distinct <em>even if</em> they work
toward the same goal: document preparation. When reading, learning,
and teaching TeX systems to others, it’s important for us to all use
the same words. After all, TeX has survived largely by word-of-mouth
recommendations and mentorship: if we start speaking different
languages, how can we learn from one another?</p>
<p>Happy TeXing!</p>
<h1 id="footnotes">Footnotes</h1>
<!-- page 47; second column -->
<div class="footnotes">
<ol>
<li id="fn:6">
<p><a href="http://maps.aanhet.net/maps/pdf/16_15.pdf">Knuth meets the Netherlands TeX Group (NTG)</a>,
page 47, second column. Donald Knuth notes “In some sense I put
in many of the programming features kicking and screaming”. TeX
was made Turing-complete after ‘intense’ lobbying by Guy Steele. <a href="#fnref:6" class="reversefootnote">&#8617;</a></p>
</li>
<li id="fn:1">
<p><a href="http://tex.stackexchange.com/a/139878/17423">A wise man once said</a>, “The most common mistake
[for beginners] is spending too long on TeX coding and not getting
the document written.”. <a href="#fnref:1" class="reversefootnote">&#8617;</a></p>
</li>
<li id="fn:7">
<p>In the programming world, it’s more appropriate to call these
‘integrated development environments’ (IDEs). That is, they
provide access to everything you need to write your document
(except your knowledge, of course). <a href="#fnref:7" class="reversefootnote">&#8617;</a></p>
</li>
<li id="fn:2">
<p>These are the official capitalizations; I promise. <a href="#fnref:2" class="reversefootnote">&#8617;</a></p>
</li>
<li id="fn:3">
<p>LuaTeX is a special animal. Since it has embedded within itself
a ‘proper’ (i.e. <em>popular</em>) programming language, Lua, most tasks
can indeed be done without leaving LuaTeX. As always, use the
best tools for the job. <a href="#fnref:3" class="reversefootnote">&#8617;</a></p>
</li>
<li id="fn:4">
<p><code>mtxrun</code> is the official way to compile ConTeXt (Mark IV)
documents and is similar in concept to <code>latexmk</code>. I don’t think
it can properly be called ‘just’ a build system; there is more
going on internally. <a href="#fnref:4" class="reversefootnote">&#8617;</a></p>
</li>
<li id="fn:5">
<p>I personally recommend <code>arara</code> – not just because I count the
developer among my friends, but because it is the only
TeX-specific tool I’ve found that doesn’t try to guess what you
want. I know what I want, the process isn’t that complicated once
you understand what’s going on, and I just want the computer to do
what I tell it to do. <a href="#fnref:5" class="reversefootnote">&#8617;</a></p>
</li>
</ol>
</div>
Mon, 25 May 2015 16:00:00 +0000http://www.seanallred.com/tex/2015/05/25/tex-terminology.html
http://www.seanallred.com/tex/2015/05/25/tex-terminology.htmltexGitHub Pages with DreamHost<p>It’s been a long, confusing day as I’ve migrated some of my old
content to Jekyll hosted by GitHub Pages served by DreamHost. In the
hopes of saving some poor soul out there the same pain I’ve been
through, I’m going to make this as simple and straightforward as I
can. I drive stick with Jekyll on Mac OS X – I do not use GitHub’s
page generator. If you want to use the page generator, you may still
use this guide as a reference, but I’m sorry that it won’t line up
perfectly.</p>
<!--more-->
<p>Assume your GitHub username is <code>bobbins</code>, your domain name is
<code>bilbo.org</code>, and you want to use <code>blog.bilbo.org</code> for your Jekyll
blog. Assume you want to store your blog at <code>~/blog</code>. (If you want
to use the <code>www</code> subdomain for your blog, it’s a little more
complicated, but that information is here, too. Read the whole
tutorial <em>before</em> you start; I backtrack a bit for <code>www</code>.)</p>
<h2 id="github">GitHub</h2>
<p>Create a new repository over at GitHub and name it</p>
<pre><code>bobbins.github.io
</code></pre>
<p>You are done on GitHub (unless you use the web to create files, in
which case, God rest your soul).</p>
<h2 id="local">Local</h2>
<p>Ensure you have Ruby, version 2 or later. The following makes a
directory in your home folder called <code>blog</code>, installs the
<code>github-pages</code> gem in the project, and scaffolds (i.e. generates) a
skeleton Jekyll site. It then creates an appropriate CNAME file and
commits everything to a git repository it initializes. Finally, it
adds GitHub as the upstream origin for your <code>master</code> branch and
pushes.</p>
<div class="highlight"><pre><code class="language-sh" data-lang="sh">mkdir ~/blog <span class="o">&amp;&amp;</span> <span class="nb">cd</span> ~/blog
<span class="nb">echo</span> <span class="s2">&quot;source &#39;https://rubygems.org&#39;&quot;</span> &gt;&gt; Gemfile
<span class="nb">echo</span> <span class="s2">&quot;gem &#39;github-pages&#39;&quot;</span> &gt;&gt; Gemfile
sudo gem install bundler
bundle install
bundle <span class="nb">exec </span>jekyll new bupkis
mv bupkis/* .
rmdir bupkis
<span class="nb">echo</span> -n <span class="s2">&quot;blog.bilbo.org&quot;</span> &gt; CNAME
git init
git commit -m <span class="s2">&quot;Initial commit&quot;</span>
git remote add origin git@github.com:bobbins/bobbins.github.io.git
git push –set-upstream origin master</code></pre></div>
<h2 id="dreamhost">Dreamhost</h2>
<ol>
<li>Login to your DreamHost control panel.</li>
<li>In the main menu (on the left sidebar), go to Domains → Manage
Domains.</li>
<li>On the left, just under your domain name, click ‘DNS’.</li>
<li>Add a custom DNS record to <code>bilbo.org</code> named <code>blog</code>, type <code>CNAME</code>,
with a value of <code>bobbins.github.io</code>.</li>
</ol>
<p>You’re done!</p>
<p>Yes, all this took me the whole day. I lost a lot of time messing
with so-called <code>A</code> records. I have to admit that I am one of those
people who has very little idea what he’s doing, but everything I
managed to do was able to be undone. In the end, it was simply a
matter of time in waiting for the changes I made to propagate to the
DNS servers. However, the longest wait was for the following change:</p>
<h2 id="using-the-www-subdomain">Using the <code>www</code> subdomain</h2>
<p>When using their web hosting service, DreamHost reserves the <code>www</code>
subdomain (among others) to manage your account. That means that you
cannot give <code>www</code> a <code>CNAME</code> record pointing to GitHub Pages.</p>
<p>If you wish to do this, you must change the type of your registration
to DNS-only. In the domain listing, under the Web Hosting column,
review the information for your domain by clicking edit. After you’ve
read and understand <em>exactly</em> what you’re about to remove, go ahead
and scroll all the way to bottom, type in <code>bilbo.org</code>, and save by
clicking ‘Host DNS Only!’. After that, change the <code>CNAME</code> file in
your repository to use the <code>www</code> subdomain. After you do this and
your changes take effect, traffic to <code>www.bilbo.org</code> will be
redirected to your Pages site.</p>
Mon, 25 May 2015 02:35:05 +0000http://www.seanallred.com/admin/2015/05/25/github-pages-with-dreamhost.html
http://www.seanallred.com/admin/2015/05/25/github-pages-with-dreamhost.htmladminWhere is LaTeX Going?<p>While I’m not a member of the LaTeX3 Project,
I find myself very much invested in its success.
Not only do I want the project to succeed in overtaking LaTeX2e,
I also want the project to make itself accessible to
those who would not have considered it in the days of 2e.
Creating a good solution requires much more thought than one would immediately think.
Considering the problem at hand will perhaps bring to light the complexities involved
and spark further conversations about potential solutions.</p>
<!--more-->
<blockquote>
<p>I think the problem, to be quite honest with you,
is that you’ve never actually known what the question is.
[…] So once you know what the question actually is,
you’ll know what the answer means.”</p>
</blockquote>
<p>LaTeX is self-described as a document preparation system.
In a separate project, I’m really pulling this apart into what it means to me
and what these deductions mean to the LaTeX Project on the whole,
but there are several aspects that I think are important to touch on.
For this article, I will discuss LaTeX’s purpose in this respect
and its inherent duty to fulfill this purpose
to the best of its ability
for everyone that wishes to take advantage of its concepts.</p>
<h2 id="a-document-preparation-system">A document preparation system</h2>
<p>What does it mean to be a ‘document preparation system’?
LaTeX works with <em>documents</em>.
It is not a movie maker.
It cannot cook rice.
It has no appreciation for the quiet stillness of a fall day during academic vacation.
It <em>does</em>, however, know how to write a document.
It knows what tools you need to be an effective author—or an effective publisher—and it provides you those tools.</p>
<p>The next logical question then is this: What is a document?
To answer this question in part, we will borrow from the documentation for <code>xtemplate</code> (written by the LaTeX3 team):</p>
<blockquote>
<p>Besides the textual content of the words themselves,
[…] a document contains mark-up elements that add structure to the document.
These elements include sectional divisions, figure/table captions,
lists of various sorts, theorems/proofs, and so on.
The list will be very different for every document that can be written.</p>
</blockquote>
<p>In short, a document consists of two distinct parts that belong together.
A document is both the text and the meaning of the text.
Any system that hopes to be a complete solution must address these goals seamlessly and simultaneously.</p>
<p>LaTeX2e solved this problem rather well;
an author imposed logical markup elements on
the plain content to create a semantically meaningful document.
However, to take advantage of this ability in a <em>practical</em> way,
it often required a non-obvious understanding of how the underlying TeX engine worked as a langauge.
As many authors can attest to, this is <em>not</em> a reasonable requirement of authors;
the author alone knows both the text and the meaning of the text,
but this author isn’t necessarily one who is familiar with computer languages
or compilation sequences.</p>
<p>Similarly, typographers are graphic designers are heart; they cannot be expected to understand the syntax of TeX.</p>
<p>Thus, an ideal world would have completely separate interfaces for
the author, the typographer/designer, and a programmer who implements it all.
This last interface is nearly complete as <code>expl3</code>;
a full-on, standardized programming environment written entirely in TeX
and requiring only the e-TeX primitives.
Upon this interface lies the whole of LaTeX3 concepts.</p>
<p>Thus, to answer this article’s question <em>where is LaTeX Going?</em>, the answer is <em>places</em>.
By truly separating the interface between authors, typographers, and programmers,
true <em>visual</em> seperation of interface is finally possible.
A graphical interface is at least <em>feasible</em> for ‘the author and certainly possible for the typographer.
The only member of the team that yet <em>needs</em> to view the internals of LaTeX
is the programmer who is likely more comfortable there anyway.</p>
<h2 id="what-about-lyx">What about LyX?</h2>
<p>LyX is oft described as a GUI front-end to LaTeX.
While it uses LaTeX as an export format,
LyX is in fact its own object.
It very much encourages the concepts of LaTeX,
but manages to use a graphical author interface.
This is <em>not</em> the same as a graphical interface to LaTeX.
It is extraordinarily difficult, in my experience, to add semantic commands to LyX.
Any author interface for LaTeX must maintain the flexibility that makes it so powerful.
This is <em>not</em> an easy problem to solve—the LaTeX3 team has been
thinking and talking for a long time on how to best approach these problems—but
it is certainly not found in LyX.</p>
Tue, 13 May 2014 00:34:41 +0000http://www.seanallred.com/tex/2014/05/13/where-is-latex-going.html
http://www.seanallred.com/tex/2014/05/13/where-is-latex-going.htmltexModern-Day TeX<p>In the very few venues that TeX known,
it is very often looked at as an antiquated technology
that has long been superseded by more ‘modern’ systems
such as the Microsoft <em>Office</em> suite of products
and the ubiquitous (and wonderful) Google Docs.
Why are TeX systems viewed like this,
and what can be done about it?
If you use TeX, is it worth it to actively show others?
If you don’t use TeX, is it worth learning,
and how much do you actually need to learn?</p>
<!--more-->
<p>There are many introductions to TeX and LaTeX on the web,
so I will not duplicate it them here.
The purpose of this post is not to introduce you to TeX,
but to show you that it isn’t difficult to use
and that it still very applicable to modern needs—yours and mine.</p>
<ul id="markdown-toc">
<li><a href="#the-powers-that-be">The powers that be</a></li>
<li><a href="#the-great-distraction">The great distraction</a></li>
<li><a href="#how-did-this-happen">How did this happen?</a></li>
<li><a href="#tex----an-alternative">TeX – an alternative</a></li>
<li><a href="#is-it-worth-teaching">Is it worth teaching?</a></li>
<li><a href="#is-it-worth-learning">Is it worth learning?</a></li>
</ul>
<h2 id="the-powers-that-be">The powers that be</h2>
<p>Microsoft <em>Word</em>, Google Docs, and similar systems are good tools for some tasks.
I can’t deny that, and I don’t intend to <a href="http://fluff.info/terrible">convince you otherwise</a>.
They are extraordinarily simple to use for extraordinarily simple documents;
I wouldn’t recommend anything else for the occasional flyer here and there.
They were developed to let anyone—even
those who were generally uncomfortable with computers—write documents
that are readable and readily reproducible.
They quickly became popular; by sheer accessibility, <em>Word</em> and friends became
<em>de-facto</em> standards in the fledgling market of ‘desktop publishing’.</p>
<p><em>Word</em> was never intended to be a fully-fledged publishing solution, however.
Microsoft’s other ‘band-aid’ products,
like <em>Publisher</em>, <em>Visio</em>, <em>Project</em>, and their sorry <em>Equation Editor</em>,
are testaments to this fact.
Still, by sheer popularity (and quite a bit of money),
the paradigm pushed its way into the market.</p>
<p>It used to be that publishing was entirely a trade of its own,
but now every author acts as artist when he weaves his words onto a WYSIWYG window.
People are used to instant gratification—even when
the gratification itself quietly becomes… insignificant.
You see, an author rarely realizes the absolute travesties
that take place under her own nose as she writes the next best-seller.
She doesn’t catch the terrible typographical mistakes that are being
made by this program that has taken no account for such from the start.
She’s focusing on writing <em>as she should be</em>,
but even now there is a flaw in the system.</p>
<h2 id="the-great-distraction">The great distraction</h2>
<p>My thoughts turn back to the words of F. P. Brooks Jr.
in his landmark work <em>The Mythical Man-Month</em>.
Inside, he marks our innate joy in creation as
a deeply human characteristic—in his words,
a reflection of God’s own joy in creation—and uses it
to explain why <em>programming</em> is fun.
It is not unreasonable to extend this inborn joy to the author in his work.
From the very start, he is shown what his work will look like when printed on a page.
(This is, after all, the entire draw of WYSIWYG.)
From this, he becomes accustomed to seeing the end result from the very beginning,
instead of going through the more traditional (and more productive, bear with me)
manuscript–edit–typeset sequence.</p>
<p>With the knowledge of how the work would be laid out,
the author can <em>easily</em> distract herself with <em>presently unimportant</em> details.
What matters in the manuscript phase is <em>content</em>, not <em>layout</em>.
This is the great distraction that plagues every author at some point or another.
What would be a blessing for very short, one-off flyers
is a hidden curse for any serious writer.</p>
<p>It extends even to publishers who would use <em>Word</em> (God rest their souls):
as a publisher—a professional in the field—you are working with
a piece of software that was specifically designed to be usable by
your lovely grandparents—who with all of their actually-valuable experience
in the physical world—are just beginning to send emails
without a worry of irreparably breaking something.
(As an aside, this actually-widespread phobia is an interesting one
and will hopefully be the subject of a later post.)
This scale of accessibility in fact <em>cripples</em> your ability
to do the job you were trained and are paid to do.
To allow time for absolutely ridiculous test cases,
actual functionality in the software is a long time coming.
To allow the average user—say, your grandmother—to make a decently-designed photo album,
the effectiveness of your expertise in the field
is crippled as <em>Word</em> carts you around in your grandmother’s wheelchair.</p>
<h2 id="how-did-this-happen">How did this happen?</h2>
<p>For real projects, this isn’t a good system for either party involved.
Why then is it still in use?
Here’s where this post becomes speculation.</p>
<p>First is the ubiquitousness of the tool.
<em>Word</em> is installed on nearly every office and academic computer.
Those that don’t have it installed can always use Google Docs.
This is a good thing and I am glad that these tools are so accessible
(even if a terrible sum of money is spent on the former).
By sheer inundation, everyone is familiar with it—everyone can write
a simple paper for class or a real letter (people still do that? <a href="Unplugged">Yes.</a>) to an old friend.</p>
<p>Second is the intuitive starting point.
When you start any of these applications,
you are unwaveringly presented with a page on which to start writing.
Since everyone has written on paper before—and I jokingly reject
your reality if you haven’t—the act of typing into something like Google Docs
is just <em>intuitive</em>.</p>
<p>Third is the ubiquitousness of the tool.
(I really think this is the big one, here.)
After all,</p>
<blockquote>
<p>An object in motion tends to stay in motion.</p>
</blockquote>
<h2 id="tex----an-alternative">TeX – an alternative</h2>
<p>Most TeX systems are not like this to a large extent.
The most essential TeX setup involves</p>
<dl>
<dt>an editor</dt>
<dd>to write your master work, providing proper project management tools
like navigation, <em>bibliography management</em>, and <em>change management</em>, and</dd>
<dt>a program</dt>
<dd>to produce a ‘camera-ready’ rendition of your work
according to the instruction of a professional.</dd>
</dl>
<p>For the author, this can be made as simple as</p>
<div class="highlight"><pre><code class="language-tex" data-lang="tex">CHAPTER. Down the Rabbit-Hole
Alice was beginning to get very tired of sitting by her sister on the
bank, and of having nothing to do: once or twice she had peeped into the
book her sister was reading, but it had no pictures or conversations in
it, `and what is the use of a book,&#39; thought Alice `without pictures or
conversations?&#39;
<span class="k">\bye</span></code></pre></div>
<p>or more popularly</p>
<div class="highlight"><pre><code class="language-latex" data-lang="latex"><span class="k">\documentclass</span><span class="nb">{</span>book<span class="nb">}</span>
<span class="k">\begin</span><span class="nb">{</span>document<span class="nb">}</span>
<span class="k">\chapter</span><span class="nb">{</span>Down the Rabbit-Hole<span class="nb">}</span>
Alice was beginning to get very tired of sitting by her sister on the
bank, and of having nothing to do: once or twice she had peeped into the
book her sister was reading, but it had no pictures or conversations in
it, `and what is the use of a book,&#39; thought Alice `without pictures or
conversations?&#39;
<span class="k">\end</span><span class="nb">{</span>document<span class="nb">}</span></code></pre></div>
<p>This is how documents would classically be authored under TeX systems.
Notice that there are no distractions such as
‘what font is used for chapters?’ or
‘how big is the page?’ or
‘does that line break look ok?’ or
<em>anything</em> of the like.
These decisions are better left to a professional or,
at the <em>very</em> least, saved for later.</p>
<p>At least in my own work, this priority of attention
to content over presentation
increases my effectiveness and creative flow when writing longer works.
Case and point: Along with several of my classmates and friends,
I am in the midst of writing my undergraduate thesis.
These are relatively monster works compared to the relative radio silence
that we are accustomed to in terms of written assignments.
(It’s nothing to scoff at as an undergraduate thesis in computer science;
twenty-five pages single-spaced with one-inch margins—which in itself
is a typographical travesty—is quite a work.)
My friends who I was able to sway to use LaTeX authored above and beyond the requirement,
while my other friends—whom I did not so convince—were typically
well <em>under</em> the requirement.
In the unfortunate even that they read this in the future,
<em>this is not a remark on your ability to write</em>.
It is shown as an example of the time and effort spent struggling with
the writing distraction that is the software you chose for familiarity.
(No but seriously <a href="http://i.imgur.com/3CWCehW.gif">I love you all</a>.)</p>
<h2 id="is-it-worth-teaching">Is it worth teaching?</h2>
<p>To those of you who know TeX and are wondering if it is worth teaching others,
the answer is an emphatic <em>yes</em>.
The friend of mine that decided to use LaTeX for his paper
made a point to thank me for the <a href="https://github.com/vermiculus/smcm-tex/blob/master/smcm-tex/cosc/smcm-cosc-smp.cls">document class</a> I provided
him (and the entire group) so that he could just <em>write</em>.
Coupled with the spotty pointers I provided him with,
he was easily able to pick it up and become self-sufficient.</p>
<h2 id="is-it-worth-learning">Is it worth learning?</h2>
<p>I won’t say LaTeX doesn’t come with a learning curve,
but I will say that the actual learning curve is gentle.
The real challenge comes in taking off the writer’s-training-wheels
you’ve become so used to and starting to ride that bike on your own!
Unless of course you don’t know how to ride a bike,
in which case I similarly (read: <em>jokingly</em>)
reject your reality and substitute my own.
I’m sure you can think of an appropriate metaphor <code>:)</code>.</p>
<p>Judge your needs based on what you’ve read above.
There is a lot more to TeX systems than just what I’ve written here, though;
for a more in-depth discussion, I will point you to
Tobias Oetiker’s <a href="http://tobi.oetiker.ch/lshort/lshort.pdf">Not So Short Introduction to LaTeX2e</a>,
Peter Flynn’s <a href="http://www.tug.org/TUGboat/tb23-2/tb74flynn.pdf">Formatting Information</a>, and
TUG’s own <a href="https://www.tug.org/begin.html">Introduction to TeX, LaTeX, and related typesetting systems</a>.
One caveat, however: if you decide you would like to try TeX,
you should try online with services such as <a href="http://www.sharelatex.com">ShareLaTeX</a> or <a href="http://www.writelatex.com">WriteLaTeX</a>
to see if you like it first, with the knowledge that a local install will be far faster.
If you want to <em>install</em> TeX locally on your computer (for free, naturally),
<em>please</em> install TeX Live if you have Windows or some Linux distribution and
MacTeX if you are using an Apple Mac running OS X.</p>
<hr />
<p>Thanks for reading!
Don’t hesitate to ask if you have questions.
If you’re reading this blog, you likely know how to get in touch. <code>:)</code>
If you don’t know how to get in touch, see the ‘About’ section above.
If you don’t feel comfortable asking me,
there are plenty of wonderful people over at <a href="http://tex.stackexchange.com">TeX.SX</a>
who would be happy to help you.</p>
<p>Toodles!</p>
Fri, 07 Mar 2014 02:29:03 +0000http://www.seanallred.com/tex/social/2014/03/07/modern-day-tex.html
http://www.seanallred.com/tex/social/2014/03/07/modern-day-tex.htmltexsocialRealizing DFAs with Raspberry Pi<p>I’ve been working on a <a href="http://www.github.com/vermiculus/pisnort">project</a> recently for a friend’s research,
which needed a decently specialized piece of hardware.
As I was at the time in a course that more-or-less guided the class
through several ‘miniature’ projects
(they weren’t really that miniature in the end),
I eagerly agreed to help her out.
Turned out to be slightly more than I bargained for.</p>
<!--more-->
<p>She needed (and is still needing;
I’m currently waiting on a motion sensor from Digikey)
a device that must turn on and off,
detect motion,
and play a sound at some delay after the motion.
It might not sound like it, but even this is a
a deterministic finite automaton (DFA).</p>
<h2 id="theory">Theory</h2>
<p>What’s a DFA, you ask?
A DFA (often simply called a <em>state machine</em>) is
a theoretical model of computation that consists of
a set of states and a set of transitions between those states.
Additionally, it defines a state to begin in
and states that make the machine happy (accept states).<sup id="fnref:formal"><a href="#fn:formal" class="footnote">1</a></sup>
DFAs account for a large portion of the embedded systems around you.
They are everywhere.
Simple devices, such as three-state lamps, as an almost trivial example.
The hardware and menu systems of television sets are another good example,
as is are most cars, traffic light systems, and every reasonable vending machine.
The little ghost-monsters in Pac-Man are floating, deadly, stress-inducing state machines.</p>
<p>So what does this all have to do with your next Raspberry Pi project?
When I came to the (recurring) realization that I was creating a real-life state machine,
the project as a whole seemed much simpler to model.
It might not seem like much, but anyone who has done any decently serious electronics work
will know that even the simplest behaviors are not trivial.</p>
<h2 id="application">Application</h2>
<p>Take, for example, the requirement of turning on and off.
Doing this with a button<sup id="fnref:hindsight"><a href="#fn:hindsight" class="footnote">2</a></sup> doesn’t seem like much at all,
but it implies quite a few things that
most normal human beings just don’t think about.
(I didn’t.)
The button will reliably be depressed for longer than a moment,
and we should not just keep toggling.
This is engineering, not heads or tails.
Thus, the button cannot simply fire a <code>toggle on/off</code> event
every time the button is depressed.
There must be something intelligent behind the curtain.</p>
<p>Enter the humble DFA.
Let’s think about the problem and define the major states for our machine:</p>
<dl>
<dt>System Off</dt>
<dd>The system is completely off.
The indicater LED is <code>LOW</code> and the motion detector is not being monitored.</dd>
<dt>System On</dt>
<dd>The system is on.
The indicator LED is <code>HIGH</code> and the motion detector is being monitored.</dd>
</dl>
<!-- [<img align="right" src="/images/rpi-dfa.png" height="350" width="350" alt="state machine"/>][tex-source] -->
<p>Let’s further define the inputs for our machine:</p>
<dl>
<dt>0</dt>
<dd>The button is not depressed.</dd>
<dt>1</dt>
<dd>The button is depressed.</dd>
</dl>
<p>We will constantly be getting inputs,
so we’ll need to have some sort of buffer area to capture excess input.
We define two more states as ‘transition states’ between on and off (and off and on)
and end up with machine on the right.</p>
<blockquote>
<p>I also used to have a nice DFA diagram, but it is also lost.</p>
</blockquote>
<h2 id="implementation">Implementation</h2>
<p>Now that we’ve formally described our system,
how do we take advantage of it?
There is a Python library for simulating state machines called <code>automata</code>
and it might simplify things for you,
but the install failed when I tried to run it and I have yet to coerce it to succeed.
It’s not too hard to create your own basic implementation, so I will put one forward here.</p>
<blockquote>
<p>I have since lost the code that was associated with this post</p>
</blockquote>
<h2 id="practice">Practice</h2>
<p>So how do we <em>use</em> what we’ve made?</p>
<blockquote>
<p>Again, it’s lost to time <code>:(</code></p>
</blockquote>
<hr />
<h3 id="footnotes">Footnotes</h3>
<div class="footnotes">
<ol>
<li id="fn:formal">
<p>Formally, DFAs (and other such models of computation) recognize a <em>language</em>.
When DFAs receive input, these chunks of input are considered as letters in a word.
If the DFA finished reading the word and is in an accept state,
the word is in the language that the machine was created to recognize. <a href="#fnref:formal" class="reversefootnote">&#8617;</a></p>
</li>
<li id="fn:hindsight">
<p>In hindsight, it would have been better to implement
this particular functionality (on/off) with a lever switch.
I believe the concept still stands, though. <a href="#fnref:hindsight" class="reversefootnote">&#8617;</a></p>
</li>
</ol>
</div>
Fri, 10 Jan 2014 00:00:00 +0000http://www.seanallred.com/cs-theory/2014/01/10/rpi-dfa.html
http://www.seanallred.com/cs-theory/2014/01/10/rpi-dfa.htmlcs-theorySyntax<p>test</p>
Wed, 03 Feb 2010 00:00:00 +0000http://www.seanallred.com/reviews/2010/02/03/syntax.html
http://www.seanallred.com/reviews/2010/02/03/syntax.htmlreviews