doc: add Seastar tutorial

This patch puts an updated version of the very partial Seastar tutorial
I once wrote for the wiki, in the doc/ directory inside the Seastar
repository. The tutorial is titled "Asynchronous Programming with Seastar",
and could use a lot more work, but with some love, it has the potential to be
very useful for aspiring authors of Seastar applications.

The document doc/tutorial.md is written in the markdown format, which
is a first for me (usually I'm a TeX aficionado), and so far seems to
be working fairly well: This file can probably be viewed directly with a
markdown viewer (e.g., on Github), but perhaps more interestingly it can be
converted to nicely formatted HTML or PDF with the commands

	ninja doc/tutorial.html
	ninja doc/tutorial.pdf

The "pandoc" command is used for these conversions, so you must have it
installed if you want to do these conversions.

Signed-off-by: Nadav Har'El <[email protected]>

configure.py

@@ -619,5 +619,13 @@ def have_hwloc():
             command = find -name '*.[chS]' -o -name "*.cc" -o -name "*.hh" | cscope -bq -i-
             description = CSCOPE
         build cscope: cscope
+        rule md2html
+            command = pandoc --self-contained --toc -c doc/template.css -V documentclass=report --chapters --number-sections -f markdown_github+pandoc_title_block --highlight-style tango $in -o $out
+            description = PANDOC $out
+        rule md2pdf
+            command = pandoc -f markdown_github+pandoc_title_block --highlight-style tango --template=doc/template.tex $in -o $out
+            description = PANDOC $out
+        build doc/tutorial.html: md2html doc/tutorial.md
+        build doc/tutorial.pdf: md2pdf doc/tutorial.md
         default {modes_list}
         ''').format(modes_list = ' '.join(build_modes), **globals()))

doc/template.css

@@ -0,0 +1,109 @@
+/* CSS style for Seastar's tutorial.
+ * TODO: We also get some style for syntax highlighting inserted by our
+ * use of "highlight-style tango" in configure.py. Perhaps we can insert
+ * this style here too, for finer control.
+ */
+
+/* Some defaults */
+body {
+	color: #000000;
+	background: #FFFFFF;
+	font-size: 13pt;
+	line-height: 1.10;
+	font-family: arial, sans-serif; 
+	margin-left: 15pt;
+	margin-right: 15pt;
+	text-align: justify;
+}
+
+/* Pandoc puts the title, author and date, if any, in its own div id="header".
+*/
+div#header {
+	border-top: 1px solid #aaa;
+	border-bottom: 1px solid #aaa;
+	background: #F0F0C0;	
+	margin: 10pt;
+	margin-left: 10%;
+	margin-right: 10%;
+}
+
+/* The title is in an h1.title, in the above div#header */
+.title {
+	color: #000000;
+	margin: 5pt;
+	text-align: center;
+	font-family: serif;
+	font-weight: bold;
+	font-size: 32pt;
+}
+/* The author/date are h2.author and h3.date */
+.author, .date {
+	color: #000000;
+	margin: 0pt;
+	text-align: center;
+	font-family: serif;
+	font-weight: normal;
+	font-size: 16pt;
+}
+
+/* table of contents is in div id="TOC" */
+div#TOC {
+	border-top: 1px solid #aaa;
+	border-bottom: 1px solid #aaa;
+	background: #F9F9F9;
+	margin: 10pt;
+	margin-left: 20%;
+	margin-right: 20%;
+}
+
+
+h1, h2, h3, h4, h5, h6 {
+	color: #EE3300;
+}
+
+a {
+	text-decoration: none;
+}
+a:link, a:visited {
+	color: #0000CC;	
+}
+a:hover {
+	color: #CC0000;
+	text-decoration: underline;
+}
+
+
+/* code snippets. The "code" elements hold individual lines, the "pre" holds everything */
+code, pre {
+    background-color: #fdf7ee;
+    background-color: #f8f8f8;
+
+    /* BEGIN word wrap */
+    /* Need all the following to word wrap instead of scroll box */
+    /* This will override the overflow:auto if present */
+    white-space: pre-wrap; /* css-3 */
+    white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */
+    white-space: -pre-wrap; /* Opera 4-6 */
+    white-space: -o-pre-wrap; /* Opera 7 */
+    word-wrap: break-word; /* Internet Explorer 5.5+ */
+    /* END word wrap */
+    }
+
+pre {
+    padding: 0.5em;
+    border: 1px dotted #777;
+    margin-left:  15pt;
+    margin-right: 15pt;
+}
+
+/* Fix stuff for printing, in case somebody tries to print the HTML instead
+ * of getting a PDF and printing that. For example, too big fonts and big
+ * margins may be a waste of paper.
+ * buttondown.css has a nice trick for replacing links with the actual text
+ * of the URL - might be nice to copy it one day.
+ */
+@media print {
+	body { font-size: 11pt; }
+	a  { color: black; background: transparent; }
+    	pre { border: 1px solid #aaa; }
+}

doc/template.tex

@@ -0,0 +1,71 @@
+% The pandoc command line (see configure.py) can communicate variables to this
+% LaTeX skelaton, by using the "-V varname=value" command line parameter, and
+% there are also some builtin variables defined by other options. With such a
+% variable, we can use "$varname$" for the value, and $if(varname)$...$endif$
+% for conditional code when this varname is defined.
+%
+% For an example of a more complete LaTeX template covering more of pandoc's
+% features, check out the example templates/default.latex in pandoc's
+% installation, or pandoc.org/demo/mytemplate.tex on their site.
+
+\documentclass[11]{article}
+\usepackage[a4paper, margin=1in]{geometry}
+\usepackage{lmodern}
+\usepackage{microtype}
+
+% Nice header with document's name and section name, and footer
+% with page number.
+\usepackage{fancyhdr}
+\pagestyle{fancy}
+\lhead{\itshape Seastar}
+\chead{}
+\rhead{\itshape{\nouppercase{\leftmark}}}
+\lfoot{}
+\cfoot{}
+\rfoot{\thepage}
+
+$if(highlighting-macros)$
+$highlighting-macros$
+$endif$
+
+% Support links in PDF files
+\usepackage[]{hyperref}
+\hypersetup{breaklinks=true,
+            bookmarks=true, % show bookmark bar (i.e, TOC sidebar) in PDF viewer
+	    pdfstartview=FitH, % cause Adobe Acrobat to do "fit to width"
+            pdfauthor={ScyllaDB},
+            pdftitle={Asynchronous Programming with Seastar},
+            colorlinks=true,  % if false, uses boxed links
+            urlcolor=blue,    % color of external links
+            linkcolor=magenta % color of internal links (to other sections)
+}
+
+% Indentation went out of style with Disco music... It is especially
+% inconvenient in text which includes a lot of code snippets, etc, which
+% causes a lot of indents not preceeded by a text paragraph. So replace
+% the indentation with increased spacing between paragraphs. Note that this
+% also makes the TOC more spacious, I'm not sure it's a great idea.
+\setlength{\parindent}{0pt}
+\setlength{\parskip}{6pt plus 2pt minus 1pt}
+
+% Fancy-formatted title, but take the author list and date (if set) from the
+% preable in the markdown file.
+\title{\textbf{\fontsize{0.75cm}{1.5em}\selectfont Asynchronous Programming} \\ \textbf{\fontsize{0.75cm}{1.5em}\selectfont with} \\ \textbf{\fontsize{3cm}{1.5em}\selectfont Seastar}}
+\author{$for(author)$$author$$sep$ \and $endfor$}
+\date{$date$}
+
+\begin{document}
+\maketitle
+
+% Table of contents, before the body of the document. Make the TOC clickable,
+% with links to the respective sections, but override the internal link color
+% set above (magenta) by normal black color, because the entire TOC being in
+% a different color looks rather conspicuous.
+{
+\hypersetup{linkcolor=black}
+\tableofcontents
+}
+
+$body$
+
+\end{document}