* Create a proper title page.
* Add header that uses the current section name.
* Format BNF for syntax extensions nicely.
* Use more compact list formats for some lists where default formats
use too much white space.
* Shorten up the document:
- Omit placeholder chapters that have little to no content.
- Omit appendices with fragments of ideas and an overview of
how to generate efficient code for array_view local variables.
- Omit appendix for array_view
The conversion from Word to LaTex lost several relatively simple
pictures. We'll replace them with pictures that will be
created using TikZ, a popular drawing package for LaTex. For those
not familiar with LaTex drawing packages, you write a series of commands that
produce a picture within the LaTex document.
This check-in is a start on replacing the first picture, which is a
diagram of how relative alignment works given an object in memory and some
pointers to the object.
The alternative of using an external program to create pictures
and insert them into a LaTex document is not attractive.
The external program has to produce PDF (or Postscript) because
that's the scalable vector graphics formats that LaTex understands.
That is then inserted into the LaTex document. PDF from the Git
perspective is a binary file: there's no sensible human merging possible
for changes. In addition, the visual results are usually poor anyway, with
mismatches in fonts, font sizes, and awkward scaling. So we'll go
with the less visual approach of "programming" pictures.
The Pandoc conversion process generated lots of unused labels.
We will not clutter the text for the document with unused labels.
It is work to keep labels up-to-date in TeX, so we'll adopt
the policy of only having labels for chapters and labelling
other sections as needed.
document.
The label names have the form the chapter:yyy or
section:yyy, where yyy is a short, unambiguous
descriptive string name for the chapter or section
with no spaces.
Names should be long enough to avoid ambiguity
when referring to concepts. For example,
function-call-argument is used instead
of function-argument because function-argument
could be ambiguously interpreted as referring to
a parameter variable.
This change creates a BibTex bib file and adds back citations
that were deleted from the document.
It also includes\ some housekeeping: add a .gitignore file to
igore files produced by LaTex. Add a special command at the
top of every LaTex file so that TexWorks knows to build the
main file for the document when you tell it to run Latex
while editing the file.
Made the following changes:
* Widen margins.
* Fixed errors in formatting of chapters and sections.
In some cases, these were formatted strangely.
* Remove unused packages from beginning of document.
* Reformat code examples and code snippets. For this,
I copied the original examples and snippets directly
from the Word document, instead of trying to fix
what Pandoc created.
* Replace \textbf with \texttt.
* Introduced macros for formatting the following kinds of
text:
- array_ptr, array_view, and ptr types.
- bounds expressions, bounds declarations,
and inference of bounds.
- keywords
- sizeof
- meta-variables: variables that range over pieces of
syntax or variables.
* Deleted the revisions log from the document. It was
not being kept up-to-date.
* Delete unnecessary hyperlink information.
I did not update the text for Chapter 6 yet (interop).
I made some changes but introduced some errors, so I
discarded the changes.
Pandoc did a way better job than just starting from plain text. However,
the Latex source needs lots of work. The formatting of code examples
and snippets was lost. Pictures, references, and cross-references are missing.
There are lots of repetitive sequences of formatting commands that should
be replaced with LaTEx macros. We'll address those issues next.
David Tarditi