1.1 --- a/preface.roff	Thu Jul 05 15:56:54 2012 +0200
     1.2 +++ b/preface.roff	Thu Jul 05 15:57:55 2012 +0200
     1.3 @@ -188,37 +188,61 @@
     1.4  
     1.5  .U2 "Organization
     1.6  .P
     1.7 -Which font for what use.
     1.8 -Meaning of `foo(1)'.
     1.9 -RFCs.
    1.10 +This thesis consists of three chapters.
    1.11 +Chapter 1 introduces into the topic, describing MH and explaining
    1.12 +the background and goals of the mmh project.
    1.13 +Chapter 2 discusses the work done in the project.
    1.14 +It is organized along the three major goals of the project, namely
    1.15 +streamlining, modernizing, and styling.
    1.16 +Not all the work done in the project is described,
    1.17 +because that would bore the reader.
    1.18 +Instead, important changes and those standing for a set of similar
    1.19 +changes are described and discussed.
    1.20 +Chapter 3 finishes up by summarizing the achivements and taking
    1.21 +an outlook to the future of the mmh project.
    1.22  .P
    1.23 -References to source code repository commits are printed as
    1.24 -.Ci 1a2b3c4 .
    1.25 -They can be looked up with
    1.26 -.Cl "git show XXX
    1.27 -on the command line or
    1.28 -online at
    1.29 -.CW "http://git.marmaro.de/?p=mmh;a=commitdiff;h=XXX" ,
    1.30 -replacing `\f(CWXXX\fP' with the hash value.
    1.31 +.I "Italic font
    1.32 +is used to emphasize new terms.
    1.33 +.CW "Constant width font
    1.34 +is used to denote names of programs, files,
    1.35 +functions, command lines, code excrepts, program input and output.
    1.36 +.P
    1.37 +References to man pages are printed as ``\c
    1.38 +.Mp cat (1)''.
    1.39 +In this case it is a reference to the man page of
    1.40 +.Pn cat ,
    1.41 +which is in section one of the Unix manual.
    1.42 +Internet technologies are specified by \fIRequests for Comments\fP (RFCs).
    1.43 +Throughout the document, they are referenced in this way ``RFC\|822''.
    1.44 +A list of relevant RFCs is located at the end of the document.
    1.45 +References to literature are printed in backets, like
    1.46 +.[ ``[
    1.47 +kernighan pike unix programming env
    1.48 +.]]'', within the text.
    1.49 +The full references are collected at the end of the document.
    1.50 +.P
    1.51 +This document describes practical programming work.
    1.52 +The code of mmh is managed by the
    1.53 +.Pn git
    1.54 +version control system.
    1.55 +All code changes were checked in.
    1.56 +In the discussions, references to corresponding code changes are printed
    1.57 +as ``\c
    1.58 +.Ci 1a2b3c4 ''.
    1.59 +The identifier is the seven-letter-prefix of the changeset hash value,
    1.60 +which is considered unique.
    1.61 +A change can be looked up in the repository, on the command line with
    1.62 +.Cl "git show XXX" ,
    1.63 +replacing `\f(CWXXX\fP' with the concrete hash value or any unique prefix.
    1.64  In this example:
    1.65 -.Cl "git show 1a2b3c4
    1.66 -or
    1.67 -.CW "http://git.marmaro.de/?p=mmh;a=commitdiff;h=1a2b3cd" .
    1.68 -Whereas the code repository will probably be available on the Internet
    1.69 -forever, a website URL is always at risk to change.
    1.70 -.P
    1.71 -This thesis is divided into XXX chapters, ...
    1.72 -.P
    1.73 -.I Chapter 1
    1.74 -introduces ...
    1.75 -.P
    1.76 -.I Chapter 2
    1.77 -describes ...
    1.78 -.P
    1.79 -.I Chapter 3
    1.80 -covers ...
    1.81 +.Cl "git show 1a2b3c4" .
    1.82 +At the time of writing, changesets can be looked up online this way:
    1.83 +.CW "http://git.marmaro.de/?p=mmh;a=commitdiff;h=XXX" .
    1.84 +But URIs are always at risk to change.
    1.85  
    1.86  
    1.87  .U2 "Acknowledgments
    1.88  .P
    1.89  To be written at the very end.
    1.90 +.P
    1.91 +FIXME