% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\usepackage[utf8]{inputenc}
\DeclareUnicodeCharacter{00A0}{\nobreakspace}
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{longtable}
\usepackage{sphinx}
\usepackage{multirow}


\title{Plaintext Editing Multi-Section Docs}
\date{March 13, 2014}
\release{1.0}
\author{Andrew Harrington, Konstantin Läufer, George K. Thiruvathukal}
\newcommand{\sphinxlogo}{}
\renewcommand{\releasename}{Release}
\makeindex

\makeatletter
\def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax%
    \let\PYG@ul=\relax \let\PYG@tc=\relax%
    \let\PYG@bc=\relax \let\PYG@ff=\relax}
\def\PYG@tok#1{\csname PYG@tok@#1\endcsname}
\def\PYG@toks#1+{\ifx\relax#1\empty\else%
    \PYG@tok{#1}\expandafter\PYG@toks\fi}
\def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{%
    \PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}}
\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}}

\expandafter\def\csname PYG@tok@gd\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gu\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@gt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.27,0.87}{##1}}}
\expandafter\def\csname PYG@tok@gs\endcsname{\let\PYG@bf=\textbf}
\expandafter\def\csname PYG@tok@gr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@cm\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@vg\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@m\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@cs\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}
\expandafter\def\csname PYG@tok@ge\endcsname{\let\PYG@it=\textit}
\expandafter\def\csname PYG@tok@vc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@il\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@go\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##1}}}
\expandafter\def\csname PYG@tok@cp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@gi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.63,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gh\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@ni\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.84,0.33,0.22}{##1}}}
\expandafter\def\csname PYG@tok@nl\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.13,0.44}{##1}}}
\expandafter\def\csname PYG@tok@nn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@no\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.38,0.68,0.84}{##1}}}
\expandafter\def\csname PYG@tok@na\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@nb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@nd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.33,0.33,0.33}{##1}}}
\expandafter\def\csname PYG@tok@ne\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.49}{##1}}}
\expandafter\def\csname PYG@tok@si\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.44,0.63,0.82}{##1}}}
\expandafter\def\csname PYG@tok@s2\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@vi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@nt\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.45}{##1}}}
\expandafter\def\csname PYG@tok@nv\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@s1\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@gp\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@sh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@ow\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@sx\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@bp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c1\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@kc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@mf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@err\endcsname{\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}
\expandafter\def\csname PYG@tok@kd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@ss\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.32,0.47,0.09}{##1}}}
\expandafter\def\csname PYG@tok@sr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.14,0.33,0.53}{##1}}}
\expandafter\def\csname PYG@tok@mo\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@kn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@o\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.40,0.40,0.40}{##1}}}
\expandafter\def\csname PYG@tok@kr\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@s\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@kp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@w\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}}
\expandafter\def\csname PYG@tok@kt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.13,0.00}{##1}}}
\expandafter\def\csname PYG@tok@sc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@k\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@se\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sd\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}

\def\PYGZbs{\char`\\}
\def\PYGZus{\char`\_}
\def\PYGZob{\char`\{}
\def\PYGZcb{\char`\}}
\def\PYGZca{\char`\^}
\def\PYGZam{\char`\&}
\def\PYGZlt{\char`\<}
\def\PYGZgt{\char`\>}
\def\PYGZsh{\char`\#}
\def\PYGZpc{\char`\%}
\def\PYGZdl{\char`\$}
\def\PYGZhy{\char`\-}
\def\PYGZsq{\char`\'}
\def\PYGZdq{\char`\"}
\def\PYGZti{\char`\~}
% for compatibility with earlier versions
\def\PYGZat{@}
\def\PYGZlb{[}
\def\PYGZrb{]}
\makeatother

\begin{document}

\maketitle
\tableofcontents
\phantomsection\label{index::doc}



\chapter{Introduction}
\label{intro:introduction}\label{intro::doc}\label{intro:plaintext-editing-multi-section-documents}

\section{Abstract}
\label{intro:abstract}
Creating Multi-Section Documents Using Free and
Open Source (FOSS) Publishing Tools

Andrew Harrington, George K. Thiruvathukal and Konstantin Läufer:
Department of Computer Science

The presenters will provide a hands-on tutorial for how to organize multi-section
documents like
\begin{itemize}
\item {} 
course texts,
\href{http://introcs.cs.luc.edu}{http://introcs.cs.luc.edu},
\href{http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml}{http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml}

\item {} 
graduate handbook,
\href{http://gradhandbook.cs.luc.edu/html/}{http://gradhandbook.cs.luc.edu/html/}

\item {} 
department courses and programs (draft),
\href{http://courses.cs.luc.edu/html/}{http://courses.cs.luc.edu/html/}

\item {} 
this sample document

\end{itemize}

using
the methods created by the FOSS community. We will cover an emerging class of
documentation tools that are based entirely on simple plaintext authoring and look at
simple authoring languages. We’ll demonstrate that although these tools were created for
software developers, they in fact are general enough to support writing across all
disciplines (e.g. humanities, arts, social sciences, life/physical sciences, and
mathematics) and are straightforward to learn.  These tools also facilitate
\emph{version control and shared repositories}
for works in progress with multiple authors.


\section{Topics}
\label{intro:topics}\begin{itemize}
\item {} 
Plain text authoring
\begin{itemize}
\item {} 
Rationale for using plain text authoring tools

\item {} 
The tool we use: Sphinx

\item {} 
Example (this talk!)

\end{itemize}

\item {} 
Collaboration tools
\begin{itemize}
\item {} 
Version control (Mercurial is our example)

\item {} 
Free online repositories for joint work (Bitbucket)

\end{itemize}

\end{itemize}


\section{History of Plaintext Authoring}
\label{intro:history-of-plaintext-authoring}
Plaintext authoring has a long history. Before there were word processors, there were
much simpler systems that were focused only on text, and formatted as a
second step. These systems are very much
still with us today.
\begin{itemize}
\item {} 
text formatting programs such as nroff (and groff)

\item {} 
generalized markup (HTML, XML, and SGML)

\item {} 
typesetting software: TeX, LaTeX

\item {} 
emerging alternatives to markup: reStructuredText and Markdown

\end{itemize}

The emerging alternatives are the subject of this demo and tutorial.


\section{Rationale}
\label{intro:rationale}
Plaintext editing represents a rather ironic direction for text editing.

Word processors were supposed to simplify writing. There are a couple of issues
with them that have developed over time:
\begin{itemize}
\item {} 
Word processors
(e.g. Word et al) became more about features than the core task of writing.

\item {} 
``Simple'' editing is generally interpreted as WYSIWYG (What you see is what you get).

\end{itemize}

WYSIWYG may be OK if you are only looking to generate a document in a single format, but
if you want to generate multiple formats simultaneously
(html, pdf, epub for ereaders, ...),
it is important to separate
\begin{itemize}
\item {} 
the content and the classifications of parts

\item {} 
the way they end up being displayed in (one of several) final products

\end{itemize}

For instance with a WYSIWYG editor you do not necessarily use the right abstractions:
you may use concrete styles (e.g., italics, large bold) instead of abstract uses
(e.g., emphasis, section heading).

In the
end, we're not proposing that folks don't use word processors, but we will focus on
what is \emph{gained} by keeping the final product in plain text.

For us, there are many advantages:
\begin{itemize}
\item {} 
lightweight

\item {} 
easy to keep in a version control system and collaborate

\item {} 
no licensing fees

\item {} 
automated indexing and cross-referencing

\item {} 
supports transformation to a myriad of formats--including Microsoft .docx itself!

\item {} 
supports proper targeting of different devices (desktop, web, mobile, e-readers)
with nearly zero effort!

\end{itemize}

The list goes on....


\chapter{reStructuredText and Sphinx}
\label{restructuredtext:restructuredtext-and-sphinx}\label{restructuredtext::doc}
Your content has parts with different uses in the text: titles, paragraphs,
emphasized text, URL's with hyperlinks, index references.  \emph{Markup} is added to
basic text content to identify these specific functions.  It is better to identify
logical function than the final appearance:
The formatting for a mobile device is quite
different than for a regular large html web page, which is different than the
formatting for a page-oriented pdf file.

In a WYSIWYG editor like MS-Word, the markup is largely hidden from you,
and you mostly look at a version formatted for a page.

If you are going to generate multiple final forms it is easier to see
the functional markup directly.
The trick is to keep the plain text concise and easily readable,
so as to not obscure the underlying text your are editing.

In the early days of the web there were no WYSIWYG editors,
and html was edited in its raw form.  Html markup is specifically
designed for web pages and can get rather verbose.

Later markup formats were structured text, and then its successor
restructured text for single files,
and then Sphinx extends restructured text
to handle multiple file organization with indexing and cross-referencing.

There are other markup systems, like \emph{markdown},
but here we cover the system we used.

In the html version of the output of this document,
you should see the link for \textbf{source} in the left html frame.
We use this document to show off some of the basic source markup.

The only markup above in this page has been
\begin{itemize}
\item {} 
the main section heading

\item {} 
paragraphs

\item {} 
italics and boldface

\item {} 
and now this
bulleted list

\end{itemize}

Look at the \textbf{source} to see the markup (link in the left frame of html output):
\begin{itemize}
\item {} 
The chapter heading is set off with a separate line of equal signs.

\item {} 
Paragraphs are left justified and separated by a blank line.  They are wrapped
in the final formatting.

\item {} 
Italics is bracketed in \emph{single asterisks}.  Boldface is
bracketed in \textbf{double asterisks}.

\item {} 
Bulleted lists look close to normal.  See that the continuation lines
like this one is indented to line up with the bullet text, not the bullet.

\end{itemize}

All of this markup is very easy to recognize and enter in the plaintext version,
though it looks better in the final formatted version.

Using chapter headings for small parts of this presentation is overkill, and
wastes space in the pdf version, but we get to see the format.


\section{This is a subsection}
\label{restructuredtext:this-is-a-subsection}
I chose dashes to indicate subsections.  You need to use a consistent symbol,
but there are many symbol characters that you can use to mark sub-sections.


\section{This is another subsection}
\label{restructuredtext:this-is-another-subsection}
And inside subsections we can have sub-sub-sections, etc.


\subsection{This is a sub-sub-section}
\label{restructuredtext:this-is-a-sub-sub-section}
I chose tildas to
identify sub-sub-sections.
\begin{quote}

This is a set-off
block of text.  See
the blank lines surrounding
a block with \emph{consistent} indentations,
further than in the surrounding section.

There may be several paragraphs in
a set-off block.
\end{quote}

From the sub-sub-section back to a sub-section:


\section{Fancier Markup}
\label{restructuredtext:fancier-markup}
There are limits to this fairly obvious spatial markup.
To mark a wider diversity of components, some explicit labels are
needed.  They come in two basic forms labeling
\begin{itemize}
\item {} 
outside a paragraph, on a line starting with ''.. ``

\item {} 
inside the flow of a paragraph

\end{itemize}


\subsection{Indexing}
\label{restructuredtext:indexing}
One of our favorite additions made by Sphinx is easy indexing.

\index{index entry!simple}
On a set off line by itself:

\begin{Verbatim}[commandchars=\\\{\}]
.. index::  index entry; simple
\end{Verbatim}

makes an index entry.  Here the primary index entry is ``index entry'',
and the secondary entry (after the semicolon) is ``simple''.

\index{double entry!index entry}\index{index entry!double entry}
Often we want to mark a place with two related idea,
and want two index entries, reversing which is primary.
You can do both simultaneously with the markup:

\begin{Verbatim}[commandchars=\\\{\}]
.. index::
   double: double entry; index entry
\end{Verbatim}

Look at the index and check.


\subsection{Footnotes}
\label{restructuredtext:footnotes}
Here we have a footnote. \footnote{
If you look at the source, you see that we are using a
double colon ::  before the set off text to make it literal.
}

Automatically numbered footnotes have a marking in place in
the source paragraph text like

\begin{Verbatim}[commandchars=\\\{\}]
[\#doubleColon]\_
\end{Verbatim}

and at the end of the section set off footnote text like

\begin{Verbatim}[commandchars=\\\{\}]
.. [\#doubleColon]
   If you look at the source, you see that we are using a
   double colon :: before the set off text to make it literal.
\end{Verbatim}

The original footnote reference inside the paragraph is bracketed by \code{{[}\#}
and \code{{]}\_}.  This follow the basic pattern in restructured text to use concise
symbol combinations inside a paragraph that are unlikely to appear in normal text.


\subsection{Links}
\label{restructuredtext:links}
There is also simple markup to do hyperlinks, both to web URL's and as
cross references within a Sphinx document, like to {\hyperref[transformation:transformation]{\emph{Transformation}}}.

More elaborate documents by some of the authors are
\href{http://introcs.cs.luc.edu}{http://introcs.cs.luc.edu} and
\href{http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml}{Dr. Harrington's Python Tutorial}.


\section{Multiple Files}
\label{restructuredtext:multiple-files}
In many situations it is useful to break up a long document into separate files.
This is particularly useful if you are collaborating.  Separating and
rearranging parts is very easy in Sphinx.  Multi-file documents can easily be
nested to any level with the toctree directive, like in the source for the
initial file for this document.

File names listed under the toctree directive can also include a toctree directive.
Just by moving single lines, you can rearrange sections.  Numbering is reworked.
Cross references still work....

This section just gave some of the flavor of Sphinx.
Look at its web site, \href{http://sphinx.pocoo.org/}{http://sphinx.pocoo.org/}, for full documentation
on installation, initiating a project, editing, and generating output formats.


\chapter{Collaboration With Bitbucket}
\label{collaboration:collaboration-with-bitbucket}\label{collaboration::doc}
If you have edited and erased large sections that you later wish you could
go back to, a version control system may be useful to you.  Version control
systems retain old versions (very efficiently with plaintext) and allow you
to easily access earlier versions and to compare versions (of plaintext)
easily.

There are many flavors.  You can use one totally on a single machine,
but with the Internet widely available, with traveling between multiple machines, and
with other possible remote collaborators, a better system is likely to have a
repository online.  A very handy option in \href{http://bitbucket.org}{http://bitbucket.org}.
It allow free access for higher ed users with any number of private contributors, and
you can chose a repository to be publicly viewable or not.

If you are collaborating, you will want to upload your changes frequently,
so your collaborator has your latest work.  Even if you are not so
conscientious, if you are working on separate files, updating is
immediate, and even if you make simultaneous separate edits to the
same plaintext file, comparison and merging changes is facilitated.

Bitbucket allows two version control systems, both free downloads.
We have been using Mercurial and there is also git.
The basic Mercurial client work from the command line, but
if that is foreign to you, there are also graphical, mouse-driven
interfaces for most operating systems and now
\href{http://blog.bitbucket.org/2011/12/21/mobile-apps-for-bitbucket/}{mobile apps}.

The source files for this presentation are at
\href{https://bitbucket.org/gkthiruvathukal/fotl}{https://bitbucket.org/gkthiruvathukal/fotl}.


\chapter{Transformation}
\label{transformation::doc}\label{transformation:transformation}\label{transformation:id1}
Of course with plaintext editing systems, there must be a separate
step to create the final output.  A big advantage is that it takes
no more work to create multiple formats:  They all are automatically
generated from your single plaintext source.

For example we can generate final documents from the source for this talk
using the program sphinx-build....


\section{Demonstration}
\label{transformation:demonstration}\begin{itemize}
\item {} 
This presentation itself is written in Sphinx with source at
\href{http://bitbucket.org/gkthiruvathukal/fotl}{http://bitbucket.org/gkthiruvathukal/fotl}
and with fairly recent formatted output at \href{http://anh.cs.luc.edu/plaintextEdit}{http://anh.cs.luc.edu/plaintextEdit}

\item {} 
\href{http://introcs.cs.luc.edu}{http://introcs.cs.luc.edu} (a work in progress for Comp 170)

\item {} 
\href{http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml}{http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml} (for Comp 150)

\item {} 
\href{http://gradhandbook.cs.luc.edu/html/}{http://gradhandbook.cs.luc.edu/html/}  Our Graduate Handbook

\item {} 
\href{http://courses.cs.luc.edu/html/}{http://courses.cs.luc.edu/html/}  draft site for course and program descriptions

\item {} 
\href{http://intronetworks.cs.luc.edu/html}{http://intronetworks.cs.luc.edu/html} (Dr. Dordal’s Networks text)

\end{itemize}

This presentation uses the Sphinx default html look and navigation.
The look is highly configurable, and then all the other documents above
except Dr. Dordal's text
use
the Sphinx \emph{bootstrap} theme.  You see rather different effects.

Demo the whole edit process:
\begin{itemize}
\item {} 
Clone the repository (typically for a new collaborator or new machine,
but it can be into a separate folder on the \emph{same} machine for a demo).

\item {} 
Add a change to source in one repository.

\item {} 
Make and view html and pdf versions.

\item {} 
Commit changes to the local repository.

\item {} 
Push changes to Bitbucket.

\item {} 
Look in Bitbucket for the diff.

\item {} 
In the second local repository, pull from Bitbucket and update.

\end{itemize}


\section{Markdown}
\label{transformation:markdown}
There are alternate systems for markup and transformation:
\begin{itemize}
\item {} 
\href{http://daringfireball.net/projects/markdown/}{http://daringfireball.net/projects/markdown/}

\item {} 
\href{http://johnmacfarlane.net/pandoc/}{http://johnmacfarlane.net/pandoc/}

\end{itemize}

Note:
Pandoc can also transform individual files between multiple formats, for instance
translate restructured text, markdown,
hmtl or latex to another one of these formats or into
docx, epub, pdf, or various slide show formats like
\href{http://meyerweb.com/eric/tools/s5/}{S5}
or \href{http://www.w3.org/Talks/Tools/Slidy2/Overview.html}{Slidy}.


\chapter{References}
\label{references:references}\label{references::doc}

\section{Resources}
\label{references:resources}
All are free downloads:
\begin{itemize}
\item {} 
Sphinx download and documentation,
\href{http://sphinx.pocoo.org/}{http://sphinx.pocoo.org/}

\item {} 
Python 2.7 required to run Sphinx (comes with a Mac, not Windows),
\href{http://python.org}{http://python.org}

\item {} 
For pretty pdf output from sphinx: Latex,
\href{http://www.latex-project.org/}{http://www.latex-project.org/}

\item {} 
Web Repository,
\href{http://bitbucket.org}{http://bitbucket.org}

\item {} 
Version Control System Usable on Bitbucket,
\href{http://mercurial.selenic.com/}{http://mercurial.selenic.com/}

\end{itemize}

This presentation:
\begin{itemize}
\item {} 
Bitbucket source: \href{http://bitbucket.org/gkthiruvathukal/fotl}{http://bitbucket.org/gkthiruvathukal/fotl}

\item {} 
As web pages:  \href{http://anh.cs.luc.edu/plaintextEdit/html}{http://anh.cs.luc.edu/plaintextEdit/html}

\item {} 
As pdf:  \href{http://anh.cs.luc.edu/plaintextEdit/PlaintextEdit.pdf}{http://anh.cs.luc.edu/plaintextEdit/PlaintextEdit.pdf}

\end{itemize}


\section{Presenters}
\label{references:presenters}\begin{itemize}
\item {} 
Dr. Andrew N. Harrington \textless{}\href{mailto:aharrin@luc.edu}{aharrin@luc.edu}\textgreater{}

\item {} 
Dr. Konstantin Läufer \textless{}\href{mailto:klaufer@luc.edu}{klaufer@luc.edu}\textgreater{}

\item {} 
Dr. George K. Thiruvathukal \textless{}\href{mailto:gthiruv@luc.edu}{gthiruv@luc.edu}\textgreater{}

\end{itemize}





\renewcommand{\indexname}{Index}
\printindex
\end{document}
