Add Pandoc Support

- Add a Pandoc defaults file
- Add a Pandoc template based on the default one
- Add chapter headers to each section

### Usage

To use, install Pandoc and ConTeXt, then simply run
`pandoc -d ./pandoc.yaml` from the repo root.

### Maintenance

When new chapters get added, the `pandoc.yaml` will need to be updated
to include each new chapter's markdown file(s).

### Miscellaneous Notes

- The PDF generated complies with PDF/A 1b:2005 by default.
- The PDF also contains the source markdown files as attachments
- All links are fully functional!
- Includes a table of contents! With links to each section!

### Conclusion

Enjoy!

.gitignore

@@ -5,3 +5,4 @@
 *.elf
 *.sym
 .DS_STORE
+os-tutorial.pdf

00-environment/README.md

@@ -1,3 +1,6 @@
+Environment
+===========
+
 *Concepts you may want to Google beforehand: linux, mac, terminal, compiler, emulator, nasm, qemu*
 
 **Goal: Install the software required to run this tutorial**

01-bootsector-barebones/README.md

@@ -1,3 +1,6 @@
+Bootsector: Barebones
+=====================
+
 *Concepts you may want to Google beforehand: assembler, BIOS*
 
 **Goal: Create a file which the BIOS interprets as a bootable disk**

02-bootsector-print/README.md

@@ -1,3 +1,6 @@
+Bootsector: Print
+=================
+
 *Concepts you may want to Google beforehand: interrupts, CPU
 registers*
 

03-bootsector-memory/README.md

@@ -1,3 +1,6 @@
+Bootsector: Memory
+==================
+
 *Concepts you may want to Google beforehand: memory offsets, pointers*
 
 **Goal: Learn how the computer memory is organized**

04-bootsector-stack/README.md

@@ -1,3 +1,6 @@
+Bootsector: Stack
+=================
+
 *Concepts you may want to Google beforehand: stack*
 
 **Goal: Learn how to use the stack**

05-bootsector-functions-strings/README.md

@@ -1,3 +1,6 @@
+Bootsector: Functions and Strings
+=================================
+
 *Concepts you may want to Google beforehand: control structures,
 function calling, strings*
 

06-bootsector-segmentation/README.md

@@ -1,3 +1,6 @@
+Bootsector: Segmentation
+========================
+
 *Concepts you may want to Google beforehand: segmentation*
 
 **Goal: learn how to address memory with 16-bit real mode segmentation**

07-bootsector-disk/README.md

@@ -1,3 +1,6 @@
+Bootsector: Disk
+================
+
 *Concepts you may want to Google beforehand: hard disk, cylinder, head, sector,
 carry bit*
 
@@ -57,7 +60,7 @@ There are two quick options:
 
 1. Try the flag `-fda` for example, `qemu -fda boot_sect_main.bin` which will set `dl`
 as `0x00`, it seems to work fine then.
-2. Explicitly use the flag `-boot`, e.g. `qemu boot_sect_main.bin -boot c` which 
+1. Explicitly use the flag `-boot`, e.g. `qemu boot_sect_main.bin -boot c` which
 automatically sets `dl` as `0x80` and lets the bootloader read data
 
 

08-32bit-print/README.md

@@ -1,3 +1,6 @@
+32-bit: Print
+=============
+
 *Concepts you may want to Google beforehand: 32-bit protected mode, VGA, video
 memory*
 

09-32bit-gdt/README.md

@@ -1,3 +1,6 @@
+32-bit: GDT
+===========
+
 *Concepts you may want to Google beforehand: GDT*
 
 **Goal: program the GDT**

10-32bit-enter/README.md

@@ -1,3 +1,6 @@
+32-bit: Enter
+=============
+
 *Concepts you may want to Google beforehand: interrupts, pipelining*
 
 **Goal: Enter 32-bit protected mode and test our code from previous lessons**

11-kernel-crosscompiler/README.md

@@ -1,3 +1,6 @@
+Kernel: Crosscompiler
+=====================
+
 *Concepts you may want to Google beforehand: cross-compiler*
 
 **Goal: Create a development environment to build your kernel**

12-kernel-c/README.md

@@ -1,3 +1,6 @@
+Kernel: C
+=========
+
 *Concepts you may want to Google beforehand: C, object code, linker, disassemble*
 
 **Goal: Learn to write the same low-level code as we did with assembler, but in C**

13-kernel-barebones/README.md

@@ -1,3 +1,6 @@
+Kernel: Barebones
+=================
+
 *Concepts you may want to Google beforehand: kernel, ELF format, makefile*
 
 **Goal: Create a simple kernel and a bootsector capable of booting it**

14-checkpoint/README.md

@@ -1,3 +1,6 @@
+Checkpoint
+==========
+
 *Concepts you may want to Google beforehand: monolithic kernel, microkernel, debugger, gdb*
 
 **Goal: Pause and organize our code a little bit. Then learn how to debug the kernel with gdb**

15-video-ports/README.md

@@ -1,3 +1,6 @@
+Video: Ports
+============
+
 *Concepts you may want to Google beforehand: I/O ports*
 
 **Goal: Learn how to use the VGA card data ports**

16-video-driver/README.md

@@ -1,3 +1,6 @@
+Video: Driver
+=============
+
 *Concepts you may want to Google beforehand: VGA character cells, screen offset*
 
 **Goal: Write strings on the screen**

17-video-scroll/README.md

@@ -1,3 +1,6 @@
+Video: Scroll
+=============
+
 *Concepts you may want to Google beforehand: scroll*
 
 **Goal: Scroll the screen when the text reaches the bottom**

18-interrupts/README.md

@@ -1,3 +1,6 @@
+Interrupts
+==========
+
 *Concepts you may want to Google beforehand: C types and structs, include guards, type attributes: packed, extern, volatile, exceptions*
 
 **Goal: Set up the Interrupt Descriptor Table to handle CPU interrupts**

19-interrupts-irqs/README.md

@@ -1,3 +1,6 @@
+Interrupts: IRQs
+================
+
 *Concepts you may want to Google beforehand: IRQs, PIC, polling*
 
 **Goal: Finish the interrupts implementation and CPU timer**

20-interrupts-timer/README.md

@@ -1,3 +1,6 @@
+Interrupts: Timer
+=================
+
 *Concepts you may want to Google beforehand: CPU timer, keyboard interrupts, scancode*
 
 **Goal: Implement our first IRQ handlers: the CPU timer and the keyboard**

21-shell/README.md

@@ -1,3 +1,5 @@
+Shell
+=====
 
 **Goal: Clean the code a bit and parse user input**
 

22-malloc/README.md

@@ -1,3 +1,6 @@
+malloc
+======
+
 *Concepts you may want to Google beforehand: malloc*
 
 **Goal: Implement a memory allocator**

23-fixes/README.md

@@ -1,3 +1,6 @@
+Fixes
+=====
+
 *Concepts you may want to Google beforehand: freestanding, uint32_t, size_t*
 
 **Goal: Fix miscellaneous issues with our code**

24-el-capitan/README.md

@@ -1,3 +1,6 @@
+El Capitan
+==========
+
 **Goal: Update our build system to El Capitan**
 
 If you were following this guide from the beginning and upgraded to El Capitan only

pandoc.context

@@ -0,0 +1,191 @@
+$if(context-lang)$
+\mainlanguage[$context-lang$]
+$endif$
+$if(context-dir)$
+\setupalign[$context-dir$]
+\setupdirections[bidi=on,method=two]
+$endif$
+% Enable hyperlinks
+\setupinteraction
+  [state=start,
+$if(title)$
+  title={$title$},
+$endif$
+$if(subtitle)$
+  subtitle={$subtitle$},
+$endif$
+$if(author)$
+  author={$for(author)$$author$$sep$; $endfor$},
+$endif$
+$if(keywords)$
+  keyword={$for(keywords)$$keywords$$sep$; $endfor$},
+$endif$
+  style=$linkstyle$,
+  color=$linkcolor$,
+  contrastcolor=$linkcontrastcolor$]
+\setupurl[style=$urlstyle$]
+
+% make chapter, section bookmarks visible when opening document
+\placebookmarks[chapter, section, subsection, subsubsection, subsubsubsection, subsubsubsubsection][chapter, section]
+\setupinteractionscreen[option={bookmark,title}]
+
+$if(papersize)$
+\setuppapersize[$for(papersize)$$papersize$$sep$,$endfor$]
+$endif$
+$if(layout)$
+\setuplayout[$for(layout)$$layout$$sep$,$endfor$]
+$endif$
+$if(pagenumbering)$
+\setuppagenumbering[$for(pagenumbering)$$pagenumbering$$sep$,$endfor$]
+$else$
+\setuppagenumbering[location={footer,middle}]
+$endif$
+$if(pdfa)$
+% attempt to generate PDF/A
+\setupbackend
+  [format=PDF/A-$pdfa$,
+   profile={$if(pdfaiccprofile)$$for(pdfaiccprofile)$$pdfaiccprofile$$sep$,$endfor$$else$sRGB.icc$endif$},
+   intent=$if(pdfaintent)$$pdfaintent$$else$sRGB IEC61966-2.1$endif$]
+$endif$
+\setupbackend[export=yes]
+\setupstructure[state=start,method=auto]
+
+% use microtypography
+\definefontfeature[default][default][script=latn, protrusion=quality, expansion=quality, itlc=yes, textitalics=yes, onum=yes, pnum=yes]
+\definefontfeature[default:tnum][default][tnum=yes, pnum=no]
+\definefontfeature[smallcaps][script=latn, protrusion=quality, expansion=quality, smcp=yes, onum=yes, pnum=yes]
+\setupalign[hz,hanging]
+\setupitaliccorrection[global, always]
+
+\setupbodyfontenvironment[default][em=italic] % use italic as em, not slanted
+
+\definefallbackfamily[mainface][rm][CMU Serif][preset=range:greek, force=yes]
+\definefontfamily[mainface][rm][$if(mainfont)$$mainfont$$else$Latin Modern Roman$endif$]
+\definefontfamily[mainface][mm][$if(mathfont)$$mathfont$$else$Latin Modern Math$endif$]
+\definefontfamily[mainface][ss][$if(sansfont)$$sansfont$$else$Latin Modern Sans$endif$]
+\definefontfamily[mainface][tt][$if(monofont)$$monofont$$else$Latin Modern Typewriter$endif$][features=none]
+\setupbodyfont[mainface$if(fontsize)$,$fontsize$$endif$]
+
+\setupwhitespace[$if(whitespace)$$whitespace$$else$medium$endif$]
+$if(indenting)$
+\setupindenting[$for(indenting)$$indenting$$sep$,$endfor$]
+$endif$
+$if(interlinespace)$
+\setupinterlinespace[$for(interlinespace)$$interlinespace$$sep$,$endfor$]
+$endif$
+
+\setuphead[chapter]            [style=\tfd\setupinterlinespace,header=empty]
+\setuphead[section]            [style=\tfc\setupinterlinespace]
+\setuphead[subsection]         [style=\tfb\setupinterlinespace]
+\setuphead[subsubsection]      [style=\bf]
+\setuphead[subsubsubsection]   [style=\sc]
+\setuphead[subsubsubsubsection][style=\it]
+
+\definesectionlevels
+   [default]
+   [section, subsection, subsubsection, subsubsubsection, subsubsubsubsection]
+
+$if(headertext)$
+\setupheadertexts$for(headertext)$[$headertext$]$endfor$
+$endif$
+$if(footertext)$
+\setupfootertexts$for(footertext)$[$footertext$]$endfor$
+$endif$
+$if(number-sections)$
+$else$
+\setuphead[chapter, section, subsection, subsubsection, subsubsubsection, subsubsubsubsection][number=no]
+$endif$
+
+\definedescription
+  [description]
+  [headstyle=bold, style=normal, location=hanging, width=broad, margin=1cm, alternative=hanging]
+
+\setupitemize[autointro]    % prevent orphan list intro
+\setupitemize[indentnext=no]
+
+\defineitemgroup[enumerate]
+\setupenumerate[each][fit][itemalign=left,distance=.5em,style={\feature[+][default:tnum]}]
+
+\setupfloat[figure][default={here,nonumber}]
+\setupfloat[table][default={here,nonumber}]
+
+\setupxtable[frame=off]
+\setupxtable[head][topframe=on]
+\setupxtable[body][]
+\setupxtable[foot][]
+\setupxtable[lastrow][bottomframe=on]
+
+$if(emphasis-commands)$
+$emphasis-commands$
+$endif$
+$if(highlighting-commands)$
+$highlighting-commands$
+$endif$
+$if(csl-refs)$
+\definemeasure[cslhangindent][1.5em]
+\definenarrower[hangingreferences][left=\measure{cslhangindent}]
+\definestartstop [cslreferences] [
+	$if(csl-hanging-indent)$
+	before={%
+	  \starthangingreferences[left]
+      \setupindenting[-\leftskip,yes,first]
+      \doindentation
+  	},
+  	after=\stophangingreferences,
+	$endif$
+]
+$endif$
+$if(includesource)$
+$for(sourcefile)$
+\attachment[file=$curdir$/$sourcefile$,method=hidden]
+$endfor$
+$endif$
+$for(header-includes)$
+$header-includes$
+$endfor$
+
+\starttext
+$if(title)$
+\startalignment[middle]
+  {\tfd\setupinterlinespace $title$}
+$if(subtitle)$
+  \smallskip
+  {\tfa\setupinterlinespace $subtitle$}
+$endif$
+$if(author)$
+  \smallskip
+  {\tfa\setupinterlinespace $for(author)$$author$$sep$\crlf $endfor$}
+$endif$
+$if(date)$
+  \smallskip
+  {\tfa\setupinterlinespace $date$}
+$endif$
+  \bigskip
+\stopalignment
+$endif$
+$if(abstract)$
+\midaligned{\it Abstract}
+\startnarrower[2*middle]
+$abstract$
+\stopnarrower
+\blank[big]
+$endif$
+$for(include-before)$
+$include-before$
+$endfor$
+$if(toc)$
+\completecontent
+$endif$
+$if(lof)$
+\completelistoffigures
+$endif$
+$if(lot)$
+\completelistoftables
+$endif$
+
+$body$
+
+$for(include-after)$
+$include-after$
+$endfor$
+\stoptext

pandoc.yaml

@@ -0,0 +1,52 @@
+from: gfm
+input-files:
+  - ${.}/README.md
+  - ${.}/00-environment/README.md
+  - ${.}/01-bootsector-barebones/README.md
+  - ${.}/02-bootsector-print/README.md
+  - ${.}/03-bootsector-memory/README.md
+  - ${.}/04-bootsector-stack/README.md
+  - ${.}/05-bootsector-functions-strings/README.md
+  - ${.}/06-bootsector-segmentation/README.md
+  - ${.}/07-bootsector-disk/README.md
+  - ${.}/08-32bit-print/README.md
+  - ${.}/09-32bit-gdt/README.md
+  - ${.}/10-32bit-enter/README.md
+  - ${.}/11-kernel-crosscompiler/README.md
+  - ${.}/12-kernel-c/README.md
+  - ${.}/13-kernel-barebones/README.md
+  - ${.}/14-checkpoint/README.md
+  - ${.}/15-video-ports/README.md
+  - ${.}/16-video-driver/README.md
+  - ${.}/17-video-scroll/README.md
+  - ${.}/18-interrupts/README.md
+  - ${.}/19-interrupts-irqs/README.md
+  - ${.}/20-interrupts-timer/README.md
+  - ${.}/21-shell/README.md
+  - ${.}/22-malloc/README.md
+  - ${.}/23-fixes/README.md
+  - ${.}/24-el-capitan/README.md
+
+to: pdf
+pdf-engine: context
+output-file: os-tutorial.pdf
+
+variables:
+  title: OS Tutorial
+  subtitle: How to create an OS from scratch
+  author: Carlos Fenollosa
+  includesource: true
+  papersize: letter
+  pdfa: true
+  linkcolor: blue
+  linkcontrastcolor: red
+
+file-scope: true
+verbosity: ERROR
+tab-stop: 4
+template: ./pandoc.context
+dpi: 300
+toc: true
+top-level-division: chapter
+reference-location: section
+number-sections: true