docs: type set manual in seL4 foundation style

Co-authored-by: Ivan Velickovic <i.velickovic@unsw.edu.au> Signed-off-by: Gerwin Klein <gerwin.klein@proofcraft.systems>
2024-06-25 20:24:37 -04:00 · 2024-06-25 20:24:37 -04:00 · c0e7c9db66
parent 04b7894ef6
commit c0e7c9db66
9 changed files with 2325 additions and 10 deletions
--- a/.github/workflows/sdk.yaml
+++ b/.github/workflows/sdk.yaml
@ -18,7 +18,7 @@ on:
 jobs:
  build_linux_x64:
    name: Build SDK (Linux x86-64)
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
    steps:
      - name: Checkout Microkit repository
        uses: actions/checkout@v4
@ -32,9 +32,13 @@ jobs:
        run: |
          rustup target add x86_64-unknown-linux-musl
          sudo apt update
+          sudo apt install software-properties-common
+          sudo add-apt-repository ppa:deadsnakes/ppa
          sudo apt install \
            cmake pandoc device-tree-compiler ninja-build \
-            texlive-fonts-recommended texlive-formats-extra libxml2-utils \
+            texlive-latex-base texlive-latex-recommended \
+            texlive-fonts-recommended texlive-fonts-extra \
+            libxml2-utils \
            python3.9 python3-pip python3.9-venv \
            qemu-system-arm \
      - name: Install AArch64 GCC toolchain
--- a/.reuse/dep5
+++ b/.reuse/dep5
@ -7,3 +7,14 @@ Files:
  tool/microkit/Cargo.lock
 Copyright: 2024, UNSW
 License: BSD-2-Clause
+
+Files:
+  docs/style/logos/blacktriangle.pdf
+  docs/style/logos/seL4-key.pdf
+Copyright: 2020, Data61, CSIRO (ABN 41 687 119 230)
+License: CC-BY-SA-4.0
+
+Files:
+  docs/style/logos/seL4-Foundation-logo.pdf
+Copyright: seL4 Project a Series of LF Projects, LLC
+License: LicenseRef-Trademark
--- a/LICENSES/LicenseRef-Trademark.txt
+++ b/LICENSES/LicenseRef-Trademark.txt
@ -0,0 +1,4 @@
+For license and usage guidelines on the seL4 trademark and logo, including
+the seL4 Foundation logo, see https://sel4.systems/Foundation/Trademark/
+
+No further license is granted from use in this repository.
--- a/build_sdk.py
+++ b/build_sdk.py
@ -13,7 +13,7 @@ than in make.

 """
 from argparse import ArgumentParser
-from os import popen, system
+from os import popen, system, environ
 from shutil import copy
 from pathlib import Path
 from dataclasses import dataclass
@ -355,6 +355,7 @@ def build_elf_component(
 def build_doc(root_dir):
    output = root_dir / "doc" / "microkit_user_manual.pdf"

+    environ["TEXINPUTS"] = "docs/style:"
    r = system(f'pandoc docs/manual.md -o {output}')
    assert r == 0

--- a/docs/manual.md
+++ b/docs/manual.md
@ -5,15 +5,13 @@

 ---
 title: Microkit User Manual (v1.2-pre)
-papersize:
- a4
-fontsize:
+documentclass: article
+classoption:
+- english
 - 11pt
-geometry:
- margin=2cm
-fontfamily:
- charter
+- a4paper
 header-includes:
+- \usepackage[makeTitle,copyright]{sel4}
 - \usepackage{titlesec}
 - \newcommand{\sectionbreak}{\clearpage}
 subparagraph: yes
@ -541,6 +539,7 @@ The `irq` element has the following attributes:
 * `irq`: The hardware interrupt number.
 * `id`: The channel identifier. Must be at least 0 and less than 63.
 * `trigger`: (optional) Whether the IRQ is edge triggered ("edge") or level triggered ("level"). Defaults to "level".
+\

 The `setvar` element has the following attributes:

@ -548,6 +547,7 @@ The `setvar` element has the following attributes:
 * `region_paddr`: Name of an MR. The symbol's value shall be updated to this MR's physical address.

 The `protection_domain` element the same attributes as any other protection domain as well as:
+
 * `id`: The ID of the child for the parent to refer to.

 ## `memory_region`
@ -802,6 +802,9 @@ For the kinds of systems targeted by the Microkit, this reduction of the usable
 The limitation on the size of by-value arguments is forced by the (architecture-dependent) limits on the payload size of the underlying seL4 operations, as well as by efficiency considerations.
 The protected procedure payload should be considered as analogous to function arguments in the C language; similar limitations exist in the C ABIs (Application Binary Interfaces) of various platforms.

+\
+\
+
 ## Limits

 The limitation on the number of protection domains in the system is relatively arbitrary.
--- a/docs/style/logos/blacktriangle.pdf
+++ b/docs/style/logos/blacktriangle.pdf
--- a/docs/style/logos/seL4-Foundation-logo.pdf
+++ b/docs/style/logos/seL4-Foundation-logo.pdf
--- a/docs/style/logos/seL4-key.pdf
+++ b/docs/style/logos/seL4-key.pdf
--- a/docs/style/sel4.sty
+++ b/docs/style/sel4.sty
@ -0,0 +1,318 @@
+% Copyright seL4 Project a Series of LF Projects, LLC
+% SPDX-License-Identifier: CC-BY-SA-4.0
+
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{sel4}[2020/09/24 v1.0 seL4 Foundation letterhead and title page]
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% Letterhead and title page for the seL4 Foundation
+%
+% Written 2020-03-23 by Gernot Heiser <gernot@sel4.systems>
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% OPTIONS:
+%   noBanner:	no black banner underneath the logo
+%   makeTitle:	generate the title header even if there is no \maketitle command
+%   copyright:	generate the copyright footer with the present year
+%
+%
+%   COMMANDS:
+%     - INPUTS:
+%        \title			Document title in header, default: none
+%        \subtitle		Document subtitle title in header, ignored if title is empty
+%        \author			Document author, ignored if title is empty
+%        \authortitle           Title of author, ignored if author is empty
+%        \email                   Contact email, ignored if author is empty
+%        \docversion          Document version
+%        \date			Date of document, default \today, ignored if title is empty
+%        \header			Organisation/originator to go in TRHS of header, multiple lines
+%					default: "The seL4 Foundation"
+%        \theurl			Org URL, default: seL4 Foundation URL
+%        \copyYear		Year of copyright (default: this year)
+%     - OUTPUTS:
+%        \doCopyright	Produces the copyright notice, must be placed
+%                                      right after \maketitle
+%					The `copyright' option is equivalent to \doCopyright immediately after \maketitle
+%        \thedocversion      Document version string
+%        \thedate                Date string
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\newif\ifb@nner\b@nnertrue
+\newif\ifm@aketitle\m@aketitlefalse
+\newif\ifc@pyright\c@pyrightfalse
+
+%% options section
+\DeclareOption{noBanner}{\b@nnerfalse}
+\DeclareOption{makeTitle}{\m@aketitletrue}
+\DeclareOption{copyright}{\c@pyrighttrue}
+
+\ProcessOptions\relax
+
+%% package section
+\RequirePackage[margin=25mm]{geometry}
+\RequirePackage{fancyhdr}
+\RequirePackage{enumitem}
+\RequirePackage{parskip}
+\RequirePackage{sfmath}
+\RequirePackage{graphicx}
+\usepackage[T1]{fontenc}
+\usepackage[sfdefault]{roboto}
+\RequirePackage{xcolor}
+\RequirePackage[iso]{isodate}
+\RequirePackage{hyperref}
+% Coloured quoted text:
+% \RequirePackage[breakable]{tcolorbox}
+\usepackage[breakable]{tcolorbox}
+
+\@titlepagetrue
+
+\if@titlepage
+\typeout{sel4 style with titlepage}
+\else
+\typeout{sel4 style without titlepage}
+\fi
+
+%% Foundation colour scheme:
+\definecolor{greenLight}{HTML}{C0DF9A}
+\definecolor{greenLogo}{HTML}{96CA50}
+\definecolor{greenDark}{HTML}{668B37}
+\definecolor{accentLight}{HTML}{D5AEAA}
+\definecolor{accent}{HTML}{AC5D55}
+\definecolor{accentDark}{HTML}{820C00}
+\definecolor{emphasisLight}{HTML}{FFE0A2}
+\definecolor{emphasis}{HTML}{FFCA5F}
+\definecolor{emphasisDark}{HTML}{B78B41}
+% white (already defined)
+\definecolor{neutralLighter}{HTML}{D6DBE4}
+\definecolor{neutralLight}{HTML}{8897AE}
+\definecolor{neutral}{HTML}{385378}
+\definecolor{neutralDark}{HTML}{263852}
+% black (already defined)
+
+\colorlet{logoGreen}{greenLogo}
+\colorlet{seL4Green}{greenLogo}
+
+% hyperref
+\hypersetup{colorlinks, allcolors=neutral, anchorcolor=black,
+            citecolor=greenDark, linkcolor=greenDark}
+% tcolorbox
+\newtcolorbox{cquote}{colback=neutralLighter,boxrule=0pt,boxsep=0pt,breakable}
+\renewenvironment{quote}
+{\list{}{\rightmargin=2ex \leftmargin=4ex}%
+ \item\relax\cquote}
+{\endcquote\endlist}
+
+%% definitions
+\renewcommand{\familydefault}{\sfdefault}
+\def\h@eader{The seL4\textsuperscript\textregistered\ Foundation\\\\}
+\def\u@rl{https://sel4.foundation}
+\def\@title{}
+\def\@subtitle{}
+\def\@author{}
+\def\@authortitle{}
+\def\@email{}
+\def\@docversion{}
+\def\@date{\today}
+\def\header#1{\def\h@eader{#1}}
+\def\theurl#1{\def\u@rl{#1}}
+\def\title#1{\def\@title{#1}}
+\def\subtitle#1{\def\@subtitle{#1}}
+\def\author#1{\def\@author{#1}}
+\def\authortitle#1{\def\@authortitle{#1}}
+\def\email#1{\def\@email{#1}}
+\def\docversion#1{\def\@docversion{#1}}
+\def\thedocversion{\@docversion}
+\def\date#1{\def\@date{#1}}
+\def\thedate{\value\@date}
+\def\thanks{\undefined}
+\newcommand{\Logo@FileName}{logos/seL4-Foundation-logo.pdf}
+\newcommand{\Triang@FileName}{logos/blacktriangle.pdf}
+\newcommand{\Key@FileName}{logos/seL4-key.pdf}
+\newcommand{\L@ogo}{\includegraphics[keepaspectratio=true,height=23mm]{\Logo@FileName}}
+\newcommand{\K@ey}{\includegraphics[keepaspectratio=true,width=1.04\paperwidth]{\Key@FileName}}
+
+%%% Produces copyright notice as a pseudo footnote without a footnote mark
+% Use it right at the top, or just after \maketitle. The optional argument is the year of the
+% copyright, it defaults to the current year.
+\newif\ifc@pyrightdone\c@pyrightdonefalse
+\newcommand{\doCopyright}[1][\the\year]{%
+  \ifc@pyrightdone\else%
+  \let\s@makefnmark=\@makefnmark%
+  \let\@makefnmark\relax%
+  \footnote{%
+    \hspace*{-1.8em}%    Magic number from article.cls/report.cls
+    Copyright \copyright~#1 seL4 Project a Series of LF Projects, LLC.\\
+    Distributed under the
+    \href{https://creativecommons.org/licenses/by-sa/4.0/legalcode}{Creative
+      Commons Attribution-ShareAlike 4.0 International (CC~BY-SA~4.0) License.}\\
+    seL4 is a trademark of LF Projects, LLC.
+  }
+  \let\@makefnmark=\s@makefnmark%
+  \c@pyrightdonetrue%
+  \addtocounter{footnote}{-1}
+}
+
+
+%% the part of the headers that's common with or without titlepage
+\def\m@akeheader{%
+  \begin{minipage}[b]{\paperwidth}%
+    \hspace*{16mm}%
+    \raisebox{2.5mm}[38mm][0mm]{\L@ogo}%
+    \hfill
+    \raisebox{4mm}{%
+      \footnotesize%
+      \textcolor{greenLogo}{
+        \begin{tabular}[b]{r}\bf
+          \raisebox{0pt}[0pt][10mm]{\rule{0pt}{8mm}}%
+          \begin{tabular}[t]{r@{}}
+            \h@eader
+          \end{tabular}\\
+          % force URL colour to be green or black, irrespective of hyperref setup
+          \bf\href{\u@rl}{\textcolor{greenLogo}\u@rl}
+        \end{tabular}
+      }%
+    }\hspace*{5mm}
+  \end{minipage}%
+}%
+
+%% the main thing: \maketitle produces the letterhead
+\if@titlepage
+\renewcommand\maketitle{%
+  \noindent%
+  \begin{titlepage}%
+    \urlstyle{sf}
+    % to suppress Overfull \hbox warnings
+    \newlength{\saveHfuzz}
+    \setlength{\saveHfuzz}{\hfuzz}
+    \setlength{\hfuzz}{\paperwidth}
+    %
+    \let\footnotesize\small
+    \let\footnoterule\relax
+    \let \footnote \thanks
+    % laying out the background
+    \newlength{\img@raise}%
+    \newlength{\img@shift}%
+    % the black triangle
+    \setlength{\img@raise}{-\paperheight}%
+    \addtolength{\img@raise}{\Gm@tmargin}%
+    \addtolength{\img@raise}{4.2mm}% don't ask me why!
+    \setlength{\img@shift}{-\Gm@lmargin}%
+    % make black triangle extend 0.1mm beyond margins to prevent a white line
+    \newlength{\img@width}\setlength{\img@width}{1.001\paperwidth}%
+    \newlength{\img@height}\setlength{\img@height}{1.001\paperheight}%
+    \addtolength{\img@shift}{-0.0005\paperwidth}\addtolength{\img@raise}{-0.0005\paperheight}%
+%    \typeout{paperheight=\the\paperheight,
+%      paperwidth=\the\paperwidth,
+%      Gm@lmargin=\Gm@lmargin,
+%      Gm@tmargin=\Gm@tmargin,
+%      img@raise=\the\img@raise,
+%      hfuzz=\the\hfuzz}
+    \raisebox{\img@raise}[0pt][0pt]{\hspace*{\img@shift}%
+      \makebox[0pt][l]{%
+        \includegraphics[keepaspectratio=false,width=\img@width,height=\img@height]{\Triang@FileName}%
+      }%
+    }
+    % header
+    \raisebox{4mm}[0pt][0pt]{\hspace*{-\Gm@tmargin}%
+      \m@akeheader
+    }%
+    %
+    \null%\vfil
+    \raggedright% to prevent stuff shifting
+    \vskip 50mm%
+    ~\hfill%
+    \makebox[0pt][r]{
+      \raisebox{0pt}[0pt][0pt]{
+        \begin{minipage}{150mm}
+          \raggedleft
+          \fontsize{36}{42}\selectfont \textcolor{greenLogo}{\@title}\\%
+          \if\@subtitle\empty
+          ~
+          \else
+          \fontsize{36}{42}\selectfont \textcolor{emphasis}{\@subtitle}
+          \fi%
+        \end{minipage}
+        \hspace*{-10mm}
+      }
+    }
+    \vskip 70mm
+    \makebox[0pt][l]{
+      \hspace*{-13mm}
+      \raisebox{0pt}[0pt][0pt]{
+        \begin{minipage}{70mm}%
+          \raggedright%
+          \color{neutral}
+          \fontsize{20}{26}\selectfont%
+          \@author\par
+          \fontsize{14}{22}\selectfont%
+          \ifx\@authortitle\empty\else\@authortitle\par\fi
+          \ifx\@email\empty\else\@email\par\fi
+          \ifx\@docversion\empty\else\@docversion\par\fi
+          \ifx\@date\empty\else\@date\par\fi
+        \end{minipage}
+      }
+    }
+  \setcounter{page}{0}
+  \end{titlepage}%
+  \thispagestyle{fancyplain}
+  \setlength{\hfuzz}{\saveHfuzz}%
+  \setcounter{footnote}{0}%
+  \global\let\thanks\relax
+  \global\let\maketitle\relax
+  \global\let\@thanks\@empty
+  \global\let\@author\@empty
+  \global\let\@date\@empty
+  \global\let\@title\@empty
+  \global\let\title\relax
+  \global\let\author\relax
+  \global\let\date\relax
+  \global\let\and\relax
+  \setcounter{page}{0}
+  \m@aketitlefalse
+}
+\else% no titlepage
+\def\maketitle{\urlstyle{sf}
+  % to suppress overfull bars in ``draft'' mode:
+  \newlength{\saveOverfullRule}
+  \setlength{\saveOverfullRule}{\overfullrule}
+  \setlength\overfullrule{0pt}
+  %
+  \noindent%
+  \raisebox{0mm}[0pt][0pt]{\hspace*{-25mm}%
+    \ifb@nner\makebox[0pt][l]{\rule{\paperwidth}{40mm}}\fi% black banner
+    \m@akeheader
+  }%
+  % reset overfull rule
+  \setlength{\overfullrule}{\saveOverfullRule}%
+  \vspace*{12mm}%
+  \ifx\@title\empty \else%
+    \begin{center}
+      {\LARGE\bf\@title\\[1ex]}
+      \ifx\@subtitle\empty \else{\Large\@subtitle} \\[1ex]\fi%
+      \ifx\@author\empty \else
+        {\Large\@author
+          \ifx\@authortitle\empty\else{\large\\\@authortitle}\fi
+          \ifx\@email\empty\else{\normalsize\\\@email}\fi
+          \\[1ex]}%
+      \fi%
+      \ifx\@docversion\empty\else\@docversion\\\fi
+      \ifx\@date\empty \else\@date \\\fi%
+      \vspace{5ex}%
+    \end{center}%
+  \fi%
+  \m@aketitlefalse
+}%\maketitle
+\fi% no titlepage
+
+\AtBeginDocument{%
+  \ifm@aketitle%
+     \maketitle%
+     \let\maketitle\relax%
+     \m@aketitlefalse%
+   \fi%
+   \ifc@pyright%
+     \doCopyright%
+   \fi%
+}