Linux on FPGA Libre docs template

5 years ago · aef89fa142
parent 20cfb9bf16
commit aef89fa142
15 changed files with 608 additions and 2 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,22 @@
+linux-fpga-libre.pdf
+linux-fpga-libre-thumbnail.pdf
+*~
+.~lock.*.ods#
+*.aux
+.fuse_hidden*
+*.glo
+*.gls
+*.idx
+*.ilg
+*.ind
+*.lof
+*.log
+*.lol
+_minted-*
+*.old
+*.out
+*.pyg
+*.swp
+*.toc
+*.xdv
+*.zip
--- a/README.md
+++ b/README.md
@ -1,3 +1,12 @@
-# linux-fpga-libre
+# Linux on FPGA Libre
+
+Linux on FPGA Libre
+
+Copyright 2019, Fork Sand, Inc.
+
+Permission is granted to copy, distribute and/or modify this document under
+the terms of the Creative Commons Attribution 4.0 International Public License
+(CC BY-SA 4.0).
+
+Published by Fork Sand, Inc., Loveland, Colorado, USA.

-Running a Linux kernel on an FPGA using 100% free software toolchain.
--- a/docs/README.md
+++ b/docs/README.md
@ -0,0 +1,14 @@
+Dependencies
+============
+Requires LaTeX.
+
+Minted syntax highlighting requires python-pygments to be installed.
+
+Build
+=====
+Run the build script to make a PDF:
+./build.sh
+
+It needs to be run twice to generate the Table of Contents and List of Figures
+the first time.
+
--- a/docs/build.sh
+++ b/docs/build.sh
@ -0,0 +1,25 @@
+#!/bin/bash
+# GPLv3+
+
+set -x
+
+rm -f linux-fpga-libre.pdf source/linux-fpga-libre.pdf
+
+cd source
+# Build main LaTeX file
+xelatex									\
+	-halt-on-error							\
+	-shell-escape							\
+	-interaction=nonstopmode					\
+	-no-pdf								\
+	linux-fpga-libre.tex
+
+# Second Pass, Build as PDF
+xelatex									\
+	-halt-on-error							\
+	-shell-escape							\
+	-interaction=nonstopmode					\
+	linux-fpga-libre.tex
+
+mv linux-fpga-libre.pdf ../
+
--- a/docs/clean.sh
+++ b/docs/clean.sh
@ -0,0 +1,16 @@
+#!/bin/bash
+
+set -x
+
+cd source || exit
+rm ./*.aux
+rm ./*.l*
+rm ./*.glo
+rm ./*.idx
+rm ./*.out
+rm ./*.pyg
+rm ./*.toc
+rm ./*.xdv
+
+rm -rf ./_minted-*
+
--- a/docs/source/Colophon.tex
+++ b/docs/source/Colophon.tex
@ -0,0 +1,31 @@
+%
+% Colophon.tex
+%
+% Linux on FPGA Libre
+%
+% Copyright (C) 2017,2018 Fork Sand, Inc.
+% Copyright (C) 2011, 2012, 2013, 2014, 2015, 2016, 2017 Aleph Objects, Inc.
+% Copyright (C) 2009, 2010 Fork Sand, Inc.
+%
+% This document is licensed under the Creative Commons Attribution 4.0
+% International Public License (CC BY-SA 4.0) by Fork Sand, Inc..
+%
+
+%%% COLOPHON %%%
+\begin{vplace}
+\centering
+\emph{\LARGE Colophon}
+
+\rule{0.5\textwidth}{0.4pt}\\[\baselineskip]
+
+{\tiny Created with 100\% Free Software}
+
+Debian GNU/Linux
+
+{\LaTeX} Memoir
+
+\rule{0\textwidth}{0pt}\\[\baselineskip]%
+\rule{0.5\textwidth}{0.4pt}\\[\baselineskip]
+\end{vplace}
+%%% END COLOPHON %%%
+
--- a/docs/source/Contact.tex
+++ b/docs/source/Contact.tex
@ -0,0 +1,17 @@
+%
+% Contact.tex
+%
+% Linux on FPGA Libre
+%
+% Copyright (C) 2017,2019 Fork Sand, Inc.
+% Copyright (C) 2011, 2012, 2013, 2014, 2015, 2016, 2017 Aleph Objects, Inc.
+% Copyright (C) 2009, 2010 Fork Sand, Inc.
+%
+% This document is licensed under the Creative Commons Attribution 4.0
+% International Public License (CC BY-SA 4.0) by Fork Sand, Inc..
+%
+
+\section{Contact}
+\setlength{\parindent}{0pt}
+Email: \texttt{info@forksand.com}
+
--- a/docs/source/Copyright.tex
+++ b/docs/source/Copyright.tex
@ -0,0 +1,37 @@
+%
+% Copyright.tex
+% Copyleft
+%
+% Linux on FPGA Libre
+%
+% Copyright (C) 2019 Fork Sand, Inc.
+%
+% This document is licensed under the Creative Commons Attribution 4.0
+% International Public License (CC BY-SA 4.0) by Fork Sand, Inc..
+%
+\fontspec{lmroman12-regular.otf}
+
+\clearpage\null\vfill
+\begingroup 
+\thispagestyle{empty}
+\footnotesize\raggedright
+\setlength{\parskip}{0.5\baselineskip}
+
+\textbf{Linux on FPGA Libre}
+
+by Fork Sand, Inc.
+
+Copyright \copyright\ 2019, Fork Sand, Inc..\par
+Permission is granted to copy, distribute and\slash or modify 
+this document under the terms of the
+Creative Commons Attribution 4.0 International Public License
+(CC BY-SA 4.0).
+
+Published by Fork Sand, Inc., Loveland, Colorado, USA.
+
+% ISBN: NNN-N-NNN-NNNNN-N
+\renewcommand{\dateseparator}{}
+\hfill\texttt{\yyyymmdddate\today} % Timestamp build date
+\endgroup
+\pagebreak{}
+
--- a/docs/source/Hardware.tex
+++ b/docs/source/Hardware.tex
@ -0,0 +1,16 @@
+%
+% Hardware
+%
+% Linux on FPGA Libre
+%
+% Copyright (C) 2019, Fork Sand, Inc.
+%
+% This document is licensed under the Creative Commons Attribution 4.0
+% International Public License (CC BY-SA 4.0) by Fork Sand, Inc..
+%
+
+\section{Overview}
+\label{sec:overview}
+
+Linux on FPGA Libre.
+
--- a/docs/source/Introduction.tex
+++ b/docs/source/Introduction.tex
@ -0,0 +1,14 @@
+%
+% Introduction.tex
+%
+% Linux on FPGA Libre
+%
+% Copyright (C) 2019, Fork Sand, Inc.
+%
+% This document is licensed under the Creative Commons Attribution 4.0
+% International Public License (CC BY-SA 4.0) by Fork Sand, Inc..
+%
+
+\section{Introduction}
+Linux on FPGA Libre.
+
--- a/docs/source/Title.tex
+++ b/docs/source/Title.tex
@ -0,0 +1,29 @@
+%
+% Title.tex
+%
+% Linux on FPGA Libre
+%
+% Copyright (C) 2017,2019 Fork Sand, Inc.
+% Copyright (C) 2011, 2012, 2013, 2014, 2015, 2016, 2017 Aleph Objects, Inc.
+% Copyright (C) 2009, 2010 Fork Sand, Inc.
+%
+% This document is licensed under the Creative Commons Attribution 4.0
+% International Public License (CC BY-SA 4.0) by Fork Sand, Inc.
+%
+
+\date {}
+\thispagestyle{empty}
+\begin{center}
+\par
+%\includegraphics[keepaspectratio=true,angle=0,height=0.95\textheight,width=0.95\textwidth]{ai-title.pdf}
+\par
+\null\vfill
+{\fontspec{lmroman12-regular.otf}\fontsize{25pt}{5cm}\selectfont \textcolor{jebba-purple}{Linux on FPGA Libre}}
+
+
+\par
+\null\vfill
+\renewcommand{\dateseparator}{}
+\hfill\texttt{\yyyymmdddate\today} % Timestamp build date
+\end{center}
+
--- a/docs/source/linux-fpga-libre-thumbnail.tex
+++ b/docs/source/linux-fpga-libre-thumbnail.tex
@ -0,0 +1,23 @@
+%
+% linux-fpga-libre-thumbnail.tex
+% Create thumbnail images of PDF pages
+%
+% Linux on FPGA Libre
+%
+% Copyright (C) 2017, Fork Sand, Inc.
+% Copyright (C) 2011, 2012, 2013, 2014, 2015, 2016, 2017 Aleph Objects, Inc.
+% Copyright (C) 2009, 2010 Fork Sand, Inc.
+%
+% This document is licensed under the Creative Commons Attribution 4.0
+% International Public License (CC BY-SA 4.0) by Fork Sand, Inc..
+%
+
+\documentclass[twoside]{minimal}
+\usepackage[paperwidth=22.86cm, paperheight=30.48cm,dvips=false,pdftex=false,vtex=false]{geometry}
+\usepackage[final]{pdfpages}
+\usepackage{pdflscape}
+\usepackage{thumbpdf}
+\begin{document}
+\includepdf[nup=2x4,pages={{},-},landscape]{linux-fpga-libre-thumbnail.pdf}
+\end{document}
+
--- a/docs/source/linux-fpga-libre.gst
+++ b/docs/source/linux-fpga-libre.gst
@ -0,0 +1,23 @@
+%
+% linux-fpga-libre.gst
+% makindex glossary style file
+%
+% Linux on FPGA Libre
+%
+% Copyright (C) 2017,2019 Fork Sand, Inc.
+% Copyright (C) 2014, 2015, 2016, 2017 Aleph Objects, Inc.
+%
+% This document is licensed under the Creative Commons Attribution 4.0
+% International Public License (CC BY-SA 4.0) by Fork Sand, Inc..
+%
+
+preamble "\\begin{theglossary}" 
+postamble "\n\\end{theglossary}\n"
+item_0  "\n\\glossitem" 
+delim_0 "{\\memglonum{" 
+encap_suffix "}}}" 
+headings_flag 0
+heading_prefix "{" 
+heading_suffix "}"
+keyword "\\glossaryentry"
+
--- a/docs/source/linux-fpga-libre.ist
+++ b/docs/source/linux-fpga-libre.ist
@ -0,0 +1,17 @@
+%
+% linux-fpga-libre.ist
+% makindex index style file
+%
+% Linux on FPGA Libre
+%
+% Copyright (C) 2017,2019 Fork Sand, Inc.
+% Copyright (C) 2014, 2015, 2016, 2017 Aleph Objects, Inc.
+%
+% This document is licensed under the Creative Commons Attribution 4.0
+% International Public License (CC BY-SA 4.0) by Fork Sand, Inc..
+%
+
+heading_prefix   "{\\normalsize \\bfseries\\hfil\\ "
+heading_suffix   " \\ \\hfil}\\nopagebreak\n"
+headings_flag       1
+
--- a/docs/source/linux-fpga-libre.tex
+++ b/docs/source/linux-fpga-libre.tex
@ -0,0 +1,313 @@
+%
+% linux-fpga-libre.tex
+% Main LaTeX document for formatting linux-fpga-libre
+%
+% Linux on FPGA Libre
+%
+% Copyright (C) 2019, Fork Sand, Inc.
+%
+% This document is licensed under the Creative Commons Attribution 4.0
+% International Public License (CC BY-SA 4.0) by Fork Sand, Inc.
+%
+
+%%% XXX NOTE
+%%% Glossaries and indices are broken:
+%%% https://sharelatex.tenderapp.com/help/discussions/questions/19378-glossaries-indices-and-speed
+%%% XXX NOTE
+
+% LaTeX Docs:
+% http://en.wikibooks.org/wiki/Category:LaTeX
+
+% LaTeX Memoir Class
+% Docs: /usr/share/doc/texlive-latex-recommended-doc/latex/memoir/memman.pdf
+\documentclass[twoside,10pt,openright,final,english]{memoir}
+
+\usepackage{tikz}
+\usetikzlibrary{shadows,shapes,arrows,chains,calc,decorations.pathmorphing,patterns,trees,positioning,automata,fit}
+% This breaks things, but would be great to use
+%\usepackage{tikz-qtree,tikz-qtree-compat}
+\usepackage{rotating}
+\usepackage{forest}
+
+\usetikzlibrary{arrows,shapes}
+\usetikzlibrary{positioning,calendar,er}
+\usetikzlibrary{decorations.markings}
+\usetikzlibrary{shapes.geometric}
+
+% Source code highlighting
+\usepackage{mdframed} % /usr/share/doc/texlive-doc/latex/mdframed/mdframed.pdf
+\usepackage{minted}   % /usr/share/doc/texlive-doc/latex/minted/minted.pdf
+\setminted{autogobble, breaklines, breakanywhere, breakautoindent, funcnamehighlighting,style=manni,fontsize=\scriptsize}
+% fontsize
+\setmintedinline{breaklines, breakanywhere}
+\surroundwithmdframed{minted}
+\mdfsetup{roundcorner=10pt,
+linewidth=3pt,
+linecolor=jebba-light-blue,
+backgroundcolor=white,
+leftmargin=1cm,rightmargin=1cm
+}
+
+\usepackage{smartdiagram}
+\usesmartdiagramlibrary{additions}
+\usepackage{comment}  % /usr/share/doc/texlive-doc/latex/comment/comment.pdf
+\usepackage{graphicx} % /usr/share/doc/texlive-doc/latex/graphics/graphicx.pdf
+\usepackage{epstopdf} % /usr/share/doc/texlive-doc/latex/oberdiek/epstopdf.pdf
+% http://www.tug.org/applications/hyperref/manual.html
+% /usr/share/doc/texlive-doc/latex/hyperref/hyperref.pdf
+\usepackage[colorlinks=true,linkcolor=jebba-dark-orange,urlcolor=jebba-dark-orange]{hyperref}
+%\usepackage{url} % /usr/share/doc/texlive-doc/latex/url/url.pdf % Use hyperref.
+\graphicspath{{./resources/}}
+
+\makeindex
+\makeglossary
+
+\usepackage{color} % Docs: /usr/share/doc/texlive-latex-base-doc/latex/graphics/grfguide.pdf
+%\usepackage[usenames,dvipsnames,svgnames,table]{xcolor}
+
+%%% PREAMBLE FONTS %%%
+% For XeTeX
+% http://www.ctan.org/pkg/fontspec
+% http://mirrors.ctan.org/macros/latex/contrib/fontspec/fontspec.pdf
+\usepackage{fontspec}
+\defaultfontfeatures{Ligatures=TeX} % To support LaTeX quoting style
+\setmainfont{lmroman12-regular.otf}
+
+\usepackage[normalem]{ulem} % underline
+
+\usepackage{floatpag} % Full page figures without page numbers.
+
+%%% END PREAMBLE FONTS %%%
+
+%%% PAGE, STOCK, AND MARGIN SIZE %%%
+% 7.44 x 9.68"   18.90 x 24.58cm
+% "Crown Quarto/Crown 4vo" at Lulu and Lightning Source 
+\setstocksize{24.58cm}{18.90cm} % { height }{ width }
+\settrimmedsize{\stockheight}{\stockwidth}{*}
+
+%\settypeblocksize{ height }{ width }{ ratio }
+\settypeblocksize{19.0cm}{*}{*}
+
+%\setlrmarginsandblock{ spine }{ edge }{ ratio }
+% make the spine have more space than outer edge
+\setlrmarginsandblock{*}{2.5cm}{1.2}
+
+% \setulmargins{ upper }{ lower }{ ratio }
+\setulmargins{2.0cm}{*}{*}
+
+% \setheadfoot{ headheight }{ footskip }
+\setheadfoot{12pt}{2cm}
+
+\checkandfixthelayout[fixed]
+%%% END PAGE, STOCK, AND MARGIN SIZE %%%
+
+\setcounter{secnumdepth}{3}
+\setcounter{tocdepth}{3}
+\setsecnumdepth{subsection}
+
+\usepackage[english]{babel}
+\usepackage{datetime} % Docs: /usr/share/doc/texlive-doc/latex/datetime/datetime.pdf
+\usepackage{ucs}
+
+%%% PDFLATEX %%%
+\usepackage{etex}
+
+%%% Not all features are used in XeTeX
+\usepackage[protrusion,babel,final]{microtype}
+%%% Conflicts with package fontspec
+%\usepackage[utf8x]{inputenc}
+
+% Docs: /usr/share/doc/texlive-humanities-doc/latex/ledmac/ledmac.pdf
+%\usepackage{eledmac}
+
+%%% linux-fpga-libre PAGE STYLE %%%
+\makepagestyle{jebbastyle}
+\pagestyle{jebbastyle}
+\makeevenhead{jebbastyle}{}{\hspace{2em}\itshape\small\leftmark}{}
+\makeoddhead{jebbastyle}{}{\scshape\small\rightmark}{}
+\makeevenfoot{jebbastyle}{}{\hspace{2em}\thepage}{}
+\makeoddfoot{jebbastyle}{}{\thepage}{}
+%%% END linux-fpga-libre PAGE STYLE %%%
+
+%%% linux-fpga-libreSKI CHAPTER STYLE %%%
+\makechapterstyle{jebbaski}{%
+  \renewcommand*{\printchaptername}{}	% Clear out the chapter name (e.g. capítulo)
+  \renewcommand*{\printchapternum}{}	% Clear out the chapter number
+  \renewcommand*{\chaptitlefont}{\fontspec{lmroman12-regular.otf}\fontsize{20pt}{3em}\selectfont}	% Set chapter title font
+  \renewcommand*{\printchaptertitle}[1]{%
+     \hrule\vskip\onelineskip \centering \chaptitlefont{##1}\par}
+  % Set chapter title font
+  \renewcommand*{\afterchaptertitle}{\vskip\onelineskip \hrule\vskip
+     \afterchapskip}
+}
+%%% END linux-fpga-libreSKI CHAPTER STYLE %%%
+
+%%% FORMATTING... %%%
+\midsloppy
+\setlength{\emergencystretch}{3em}
+\tolerance=5000
+\hyphenpenalty=500
+\setlength{\topskip}{1.6\topskip}
+\checkandfixthelayout
+\raggedbottom
+\widowpenalty=10000
+\clubpenalty=10000
+%%% END FORMATTING... %%%
+
+%%% FOOTNOTES %%%
+% no horizontal rule before footnotes:
+\let\oldfootnoterule\footnoterule
+\renewcommand*{\footnoterule}{}
+\setlength{\footmarkwidth}{3.5em}
+%%% END FOOTNOTES %%%
+
+%%% COLORS %%%
+\definecolor{jebba-purple}{cmyk}{0.40,0.70,0.00,0.43}  % ???
+%\definecolor{jebba-purple}{cmyk}{0.84 0.80 0.00 0.04} % ???
+\definecolor{jebba-dark-blue}{cmyk}{0.83 0.24 0.00 0.22}
+\definecolor{jebba-light-blue}{cmyk}{0.42 0.24 0.00 0.08}
+\definecolor{jebba-light-orange}{cmyk}{0.00 0.40 0.88 0.03}
+\definecolor{jebba-dark-orange}{cmyk}{0.00 0.42 0.83 0.22}
+\definecolor{jebba-gold}{cmyk}{0.00 0.28 0.74 0.00}
+\definecolor{jebba-greyblack}{cmyk}{0.00 0.22 0.08 0.87}
+\definecolor{jebba-white}{cmyk}{0.00 0.00 0.00 0.00}
+\definecolor{jebba-black}{cmyk}{1.00 1.00 1.00 1.00}
+\definecolor{jebba-green}{cmyk}{0.22 0.00 0.78 0.24}
+%%% END COLORS %%%
+
+
+%%% DEBUG %%%
+%\showoutput
+%\typeoutlayout
+%\typeoutstandardlayout
+%%% END DEBUG %%%
+
+%%% END OF PREAMBLE %%%
+
+\begin{document}
+
+%%% BEGIN FRONT MATTER %%%
+\frontmatter
+
+% Set page numbers to lowercase roman numerals, and reset the count to 1 (no *)
+\pagenumbering{roman}
+
+%%% TITLE PAGE %%%
+% We want the title to be on the right hand page.
+% If we pad a page, it gives us two with openright
+\include{Title}
+%%% END TITLE PAGE
+
+%%% COPYRIGHT PAGE %%%
+\include{Copyright}
+%%% END COPYRIGHT PAGE %%%
+
+%%% TABLE OF CONTENTS %%%
+{\fontspec{lmroman12-regular.otf}
+\maxtocdepth{subsection}
+\settocdepth{subsection}
+%\setsecnumdepth{subsection}
+% space between dots
+\renewcommand{\cftchapterdotsep}{15}
+% dot symbol (default is period)
+\renewcommand{\cftdot}{\textperiodcentered}	% centered period
+% Set space between each entry in ToC
+\setlength{\cftbeforechapterskip}{5pt}
+\tableofcontents*}
+%%% END TABLE OF CONTENTS %%%
+
+%%% LIST OF FIGURES %%%
+\renewcommand*{\lofheadstart}{\vspace{1cm}}
+\clearpage
+\listoffigures*
+%%% END LIST OF FIGURES %%%
+
+%%% LIST OF LISTINGS %%%
+%\renewcommand*{\lofheadstart}{\vspace{1cm}}
+%\clearpage
+%\listoflistings
+%%% END LIST OF LISTINGS %%%
+
+%%% CHAPTER STYLE %%%
+\chapterstyle{jebbaski} % defined in preamble
+\def\topblockvspace{0.11}
+%%% END CHAPTER STYLE %%%
+
+%%% CHAPTER CONFIG %%%
+\newcommand{\chapterheader}{Linux on FPGA Libre}
+% See \chapterconf below for examples of how this is used.
+% value 1 is file to include
+% value 2 is title of chapter
+% value 3 is sub title of chapter
+\newcommand{\chapterconf}[3]{
+\chapter{\emph{{#2}}\protect \\
+{#3}}
+\thispagestyle{empty}
+\markboth{#2}{\chapterheader}
+{\include{#1}}
+}
+%%% END CHAPTER CONFIG %%%
+
+%%% FRONTMATTER CHAPTERS %%%
+\fontspec{lmroman12-regular.otf}
+
+% Format:
+% \chapterconf{Name of file to include}{Title of Chapter}
+\chapterconf{Introduction}{Introduction}{Linux on FPGA Libre}
+%%% END FRONTMATTER CHAPTERS %%%
+
+%%% END FRONTMATTER %%%
+
+%%% BEGIN MAINMATTER %%%
+\mainmatter*
+
+% Set page numbering to arabic, but don't reset numbering (*)
+\pagenumbering*{arabic}
+
+%% MAINMATTER CHAPTERS %%%
+% Default chapter font
+\fontspec{lmroman12-regular.otf}
+
+% Format:
+% \chapterconf{Name of file to include}{Title of Chapter}{Subtitle}
+% Comment out a line to not render that chapter
+\chapterconf{Hardware}{Hardware}{Hardware}
+\chapterconf{Contact}{Contact}{Email}
+%% END MAINMATTER CHAPTERS %%%
+
+%%% END MAINMATTER %%%
+
+%%% BEGIN BACKMATTER %%%
+\backmatter
+
+%%% INDEX %%%
+\clearpage
+\printindex
+%%% END INDEX %%%
+
+%%% GLOSSARY %%%
+\renewcommand{\memgloterm}[1]{\textbf{#1}}
+\renewcommand{\memglodesc}[1]{\textit{#1}}
+\renewcommand{\memglonum}[1]{}
+
+\clearpage
+\printglossary
+%%% END GLOSSARY %%%
+
+%%% COLOPHON %%%
+%%% skip a couple pages
+\pagebreak{}
+\thispagestyle{empty}
+\begingroup 
+\vfill\null 
+\endgroup
+\pagebreak{}
+\thispagestyle{empty}
+\fontspec{lmroman12-regular.otf}
+{\include{Colophon}}
+%%% END COLOPHON %%%
+
+%%% END BACKMATTER %%%
+
+\end{document}
+