Introduction

ConTeXt, because TeXinfo, Muse and LaTeX are not the best tools for writing/creating books, papers, flyers, booklets, reports, magazines, theses, etc. these days. TeXinfo is great when it comes to write manuals for FLOSS (Free/Libre Open Source Software). Muse is awesome to have your website done with (which happens to be a Wiki in most cases). LaTeX is kind of outdated although I happily used it for years and still think it is a great tool set.

However, the above words are my current point of view. They are therefore totally biased and subjective. Others might have other opinions on the matter which is of course perfectly fine... In general, there is nothing like The best tool is... — all of the afore mentioned tools have their strengths and weaknesses depending on what task at hand.

Why ConTeXt?

As we already know, ConTeXt is basically just another TeX distribution — I have been with LaTeX and TeXinfo before. I used LaTeX to create both of my master theses among many other documents. Pretty much at the same time I started to use TeXinfo. TeXinfo is quite cool when it comes to have one source file and the need to create several output formats from it e.g. XHTML, PDF, GNU Info, etc. Then after a while I discovered Muse — which is what I use for this website/platform.

Anyway, some time ago, I was confronted with the task to write a series of technical papers for some clients in the financial sector. What tool should I use?

LaTeX nor TeXinfo seemed quite right at this time. LaTeX would be all right since I needed to deal with mathematical formulas a lot but then there are those nasty package clashes that I am tired off. So, no LaTeX. Also no TeXinfo since formulas with TeXinfo... well, I have been there... still hurts... simply a no-go. As for TeXinfo, Muse is a no-go in case one needs heavy mathematics in his document. I also needed something to create some funky graphics and a nice-looking, professional layout So?... OpenOffice?... Not really. Real man do not use the mouse ;-]

Well, long story made short — ConTeXt provides me with no headache because of dump package clashes, has a modern concept (compared to LaTeX), allows for formulas which turn our brains upside down and ships with the power of Metafun i.e. mind-blowing layout at our fingertips.

Attitude and Quality

Last but not least, anyone serious about writing a book will find nothing better than ConTeXt to do so. However, please note, ConTeXt is a technology — nothing more, nothing less. Although smart, powerful and accurate, the outcome can just be as good as is the human part and the technology part taken together — if one of them is crap, the outcome will certainly be crap too. What that means is obvious:

I have seen Professors writing papers and theses using Open Office respectively Microsoft Word. Well, as one would expect, the result pretty much was crap — maybe not so much from the contents point of view but certainly from the layout point of view — in the end, content always suffers from bad layout too, at least that is my experience. I have also seen unskilled/inexperienced/dump/lazy students writing their papers/theses with LaTeX, they too produced crap.

As the heading says, being serious about getting into the heavens of professional typesetting takes time. Those who are new to the whole matter of professional typesetting and thus some tool that actually allows to do so (and no, Microsoft Word, OpenOffice and friends do not belong to this group) and think they might produce mind-blowing results after 2 weeks... well, then better stick to OpenOffice or even worse, Microsoft Word because great results after 2 weeks... not going to happen!

Book design is the art of incorporating the content, style, format,
design, and sequence of the various components of a book into a
coherent whole.
      — (Wikipedia)

On the other hand, if the reader is more the kind of person who approaches things from the academic angle i.e. reading around for a few weeks, testing and trying for another month, getting a feeling for the things and starting all over the right way three months after first contact, then ConTeXt is for him. Even more so if he finds it great to learn new things and mind-boggling stuff after already using it for 2 years on a regular...

The good news is, even if it takes a few months, one already knows at the beginning that once he climbed that mountain there is no other higher that the one he stands on top after a somewhat strenuous way up there... With stuff like OpenOffice, one basically resides at base camp zero for his whole life...

If that is enough for the reader, then he can stop reading and enjoy some other stuff right now. On the other hand, if that is not the case and he feels a certain itch that tells him to climb this mountain no matter what, well then continue reading might be a good idea.

As I have said, I tried pretty much anything out there, wrote books, master theses, PhD thesis (yet to be written), articles, reports and whatnot. ConTeXt is the best I came across so far. I think I am pretty good settled when I say, I am going to use ConTeXt for anything book, report, article, folder, thesis like... i.e. whenever superior typesetting, layout, graphics and formulas are needed. TeXinfo for all the FLOSS (Free/Libre Open Source Software) stuff i.e. a lot of screen dump with examples from the CLI (Command Line Interface) etc. and Muse for my blog, website and PIM (Personal Information Manager) because of its great wiki-like feeling. Sorry LaTeX, we had our time and it was nice but you are just to old for a young and handsome guy like me ;-]

Getting Started

This section is about how to get started. Of course I use GNU Emacs to write my ConTeXt documents. Emacs has a mode called AucTeX which can be used to create LaTeX, ConTeXt etc. documents. Those who are already familiar with AucTeX know that Emacs mode is mind-blowing. Note that there are many editors that can produce ConTeXt code — however, as always, Emacs is superior over any other.

Acquiring the Software

We need to get ConTeXt itself plus (just in case we are going to use GNU Emacs) AucTeX and Emacs itself. That said, for the sake of completeness it also has to be said that basically any text editor can be used to create ConTeXt source code i.e. GNU Emacs is not obligatory but I strongly recommend it.

ConTeXt

On DebianGNU/Linux all we need to do is to install a few packages

sa@wks:~$ dpl {auctex,context} | grep ^ii
ii  auctex                               11.83-7.1                  integrated document editing environment for TeX etc.
ii  context                              2008.01.28-1               powerful TeX format
sa@wks:~$

i.e. apt-get install auctex context or aptitude install auctex context.

GNU Emacs

Those who have not installed GNU Emacs yet might install it. There are many ways to do so. One way to have an up-to-date GNU Emacs all the time with pretty much no effort at all is to put the following entry in

,----[ grep emacs /etc/apt/sources.list ]
| # emacs snapshot
| deb http://emacs.orebokech.com sid main
| deb-src http://emacs.orebokech.com sid main
`----

and then install a few packages

sa@wks:~$ dpl emacs* | grep ^ii
ii  emacs-goodies-el                     29.2-1                     Miscellaneous add-ons for Emacs
ii  emacs-jabber                         0.7.1-4                    Jabber client for Emacsen
ii  emacs-snapshot                       1:20080406-2               The GNU Emacs editor (development snapshot)
ii  emacs-snapshot-bin-common            1:20080406-2               The GNU Emacs editor's shared, architecture
ii  emacs-snapshot-common                1:20080406-2               The GNU Emacs editor's common infrastructure
ii  emacs-snapshot-el                    1:20080406-2               GNU Emacs LISP (.el) files
ii  emacs-snapshot-gtk                   1:20080406-2               The GNU Emacs editor (transitional package)
ii  emacsen-common                       1.4.17                     Common facilities for all emacsen

Customizing GNU Emacs

Finally we need some .emacs magic to make writing ConTeXt documents a joy like nothing else... Generally, reading the AucTeX Info manual is a good start anyway C-h i dm auc TAB RET should bring us right to

I am not going to explicitly provide and explain stuff here since my .emacs does it anyway plus this way it is ensured the information is always up-to-date. Just look out for the

[skipping a lot of lines...]


;;;_ Document Engineering

;;;_. auctex

;;;_ , initialize some stuff

(load "auctex.el" nil t t)
(load "preview-latex.el" nil t t)

(setq TeX-auto-save t)
(setq TeX-parse-self t)
(setq TeX-auto-untabify t)
(setq TeX-display-help t)
(setq TeX-save-query nil)
(setq TeX-clean-confirm nil)
(setq-default TeX-master nil)


;;;_ , hook(s)
(add-hook 'TeX-mode-hook (lambda () (TeX-fold-mode 1)))
(add-hook 'TeX-mode-hook (lambda () (TeX-source-specials-mode 1)))
(add-hook 'TeX-mode-hook (lambda () (TeX-toggle-debug-bad-boxes)))
(add-hook 'TeX-mode-hook (lambda () (TeX-toggle-debug-warnings)))
(add-hook 'TeX-mode-hook (lambda () (outline-minor-mode)))
(add-hook 'TeX-mode-hook (lambda () (abbrev-mode t)))
(add-hook 'TeX-mode-hook (lambda () (auto-fill-mode 1)))

(add-hook 'TeX-mode-hook 'LaTeX-math-mode)

;;;_ , etexshow

(autoload 'etexshow "etexshow"  "Browswer for ConTeXt commands." t)


(setq etexshow-xml-files-alist
  `((,(concat emacs-root-dir "libs/etexshow/cont-en.xml") .
     ,(concat "/tmp/cont-en.cache"))))


(setq etexshow-comment-file
  (concat emacs-root-dir "libs/etexshow/cont-en-comments.xml"))


;;;_. doc-view

(setq TeX-PDF-mode t)
(setq revert-without-query '(".+pdf$"))
(add-hook 'doc-view-mode-hook 'auto-revert-mode)

[skipping a lot of lines...]

part. Also, note doc-view stanza. With it we can view PDFs inside an Emacs buffer and it also gets reloaded/reverted automatically every time we process our document.

Structure

Writing some report, article, magazine, book etc. always boils down to how to structure information. Before we start thinking about a decent project structure we have to step back one further step and take a look at the big picture.

A prerequisite to create a decent project structure — making use of a technology in order to map ones thoughts into something others can pick up — is to get the overall picture of the whole process. Here is what needs to be done:

1. At first we should spend a few days wrapping our minds around what it takes to create outstanding writings. Just sitting down and start typing (even though we might already be ConTeXt experts) is not going to fly since after a few pages one question pops up... How do I organize the Information? Again this phase is not about the technology used i.e. not about if we might either use LaTeX, ConTeXt, OpenOffice or something else. It is about writing a book.
2. The next step is already about ones specific information and how it needs to be prepared in order to reflect the things about writing a book. This is usually the phase where folks should take a pencil and a few sheets of paper and hide themselves away somewhere. This phase is crucial! If it goes wrong it could end badly — ever needed to restructure respectively rewrite a 700 pages book because I was in a hurry to start writing? That is fun! Takes you about three times as long compared to what had happened if it would have been done right in the first place i.e. not rushing trough the pen and sheets phase. My experience is that most folks skip this phase entirely — they simply never thought about it this way. I would say that around 80% percent of all master/doctoral theses are like this — only causing confusing even though distinct chapters an parts might be coherent but not the big picture.
3. Now that we know what it takes to write a book from phase 1 plus that we have structured our information during phase 2, we can start using some technology e.g. ConTeXt. In other words — we need to find some mapping so we can map the outcome from phase 2 onto the structure from phase 1, which happens to be a book in our case. The missing link here is ConTeXt's project structure which we will use to do the mapping.

General Document Structure

This section tells about what I do in chronological order. From the link above we know that we need to know how to write a book/document first.

A document will be divided in functional components like introductions and appendices
with their respective (typographical) characteristics.
      — excerpt from some ConTeXt manual

Before we actually go into detail on the document structure we should know that there are several approaches depending on objective things like what kind of document is going to be written or other, more subjective, reasons like for example the personal likings of some author. More information on that matter can be found in chapter 8 of this manual.

Step 1 - The Layout

At first I think about the layout:

• typography
• front and back cover
• page layout

Mostly, what influences this decicision is the supposed readership and the writings purpose — a doctoral thesis has a different layout than a 90 pages business plan. And of course those two a have a totally different layout compared to some booklet or an event flyer for some vernissage.

Step 2 - The front matter

The front matter consists of all or just a few of the following parts:

• non-standard: Meta Data (this one is a bit special as we will see further down)
• Front cover
• non-standard: Vita (I simply decided I wanted A) a short vita (one page for text and picture) and B) it should go here)
• Half title or Bastard title
• Frontispiece
• Title page
• Edition notice
• Table of contents
• List of figures
• List of tables
• Foreword
• Preface
• Acknowledgements
• Dedication
• Introduction
• Prologue

Of course, a flyer might not have any of the front matter parts. A book on the other hand might come with all of the above and a very detailed technical report might also have almost all of the front matter parts included but might have a little bit of a different naming for them e.g. what is called Prologue with a book might be called

• Abstract with technical writings
• Preamble with contracts
• Opening Credits with some movie
• Overture with the opera

Sounds complicated? Yes, a little bit for those who are entirely new to the matter of how to create an outstanding piece of writing — something that deserves to be read by others, something that is not just wasting the most valuable thing (time) a living organism possesses and something that makes people forget about time and space, lets them disappear from their environment with something in their hands called a book.

As it can be seen, one might really lean back, take a deep breath and provide himself with some ambiental space that suits the situation (music, tea, landscape, etc.) in order to acquire that new knowledge. Rushing through this phase would result in producing crap... We do not want that nor are we satisfied with creating average work — we want to climb on top of the things possible no matter what! Antonio Vivaldi's violin concerts and a cup of green tea with ginger help (me) a lot with such undertakings.

Step 3 - The body

This part is easy to understand and I would guess anyone ever written anything more than a flyer is already familiar with the Body of some writing. The Body matter usually includes:

• Parts
• Chapters
• Sections
• Subsections
• and so on...

Of course, a flyer or booklet might not be build from any of these structural items at all. A flyer for example might just be one sheet of paper. A booklet might have around 5 pages and therefore could already have parts. For example, let us assume we are creating a booklet which is an invitation for some business dinner. It has three parts — 1) who is the host and why is it happening, 2) what will the evening program be and last but not least, 3) a description of the location and how to get there.

The more experienced folks and/or the attentive reader might also think by himself... Well, I know there are parts, chapters, sections, etc. but how do I split the things to be written among them? This is a gvery good question! We talk about that later on in phase 2...

Step 4 - The back matter

As for the front matter, not anyone might be an expert on this structural part of document e.g. book, magazine, etc.

• Epilogue
• Extro/Outro
• Afterword
• Conclusion
• Postscript
• Appendices/Addendum/Appendix
• Glossary
• Bibliography
• Index/Register
• Colophon

As for the front matter and the body part — a book might contain all the upper listed items but other writings might just have a subset or maybe even none of the back matter items listed above.

Structuring the Information

Ha! That one is easy... Why? Well, because anything said about this phase is wrong and right at once — there are absolutely no generic rules — just per-person opinions. The outcome of this phase depends on the information itself, the individual and its point of view, the society an individuals lives in, current scientific facts, etc.

However, here is what I do: My rationale about how to approach this issue is mainly dependant on the type of knowledge and the type of document I am writing. The way I figure it makes sense to structure the information is actually trivial and therefore ingenious at once:

• one-dimensional: a writing might be structured by time or
• one-dimensional: by some functional context or
• two-dimensional: a mixture of the two (which I would say is true for the majority off writings)
• multi-dimensional: no general statement possible... This one heavily depends on the overall subject. As an example of some project management I did — it included the parameter individual next to time and functional context. Individuals can come alone, be grouped together etc.

One-dimensional Examples

Biography

A biography might be more or less an enumeration of what someone did during his life. For example, there might be several parts — childhood, puberty, adult live, etc. The part childhood might then have several chapters. Chapter one might span from moment of birth till age 3. Chapter from age 4 to age 8 and so on.

This example uses just time to structure its information/content. No functional distinctions are made.

Painting

Some art critic might structure his paper by functionality only. He might write about some painting technique in part one. Chapter one of part one might for example discuss how well the artist performs with his paintbrush and so on. Part two might then be about the quality of the material that has been used to create the painting. Chapter one of part two might for example discuss the canvas. Chapter two of part two might be about paint.

This example is just about functionality and does not use time to structure the information.

Two-dimensional Example

A tech paper

Some company having some pain i.e. they want to improve things with for example their IT (Information Technology). There is no need to go into detail but usually a good analyst/consultant looks at the whole shebang not just from different angles (finance's, technology, usability, etc.) but also includes one utterly important constraint in his consideration — the base SI unit time into account i.e. past, present and future state. Based on that, he comes up with a plan that improves not just the current state but also has some long-term impact on the overall picture.

This example is of the latter type of the three afore mentioned possibilities since it is pretty much two-dimensional. We got time and we got functionality. Whether or not the resulting writing has three parts (past, present, future (or more than three)) which are each divided into several chapters (finance's, technology, etc.) or the other way around (one part for any functional matter, divided into past, present and future) depends on the particular case/issue.

Project Structure

This is where we actually make first contact with the technology we are going to use — during phase 1 and 2 nobody needs to take care about the technology that will finally be used to create a document!. The image below shows what is a typical ConTeXt project structure:

Further down we will see how to create such a project structure starting with the project files (Project and Environment). After the project files we create the product files and after those have been created the last thing to do is to create the component files. Any of those files is a plain text file and can be edited with any editor of choice e.g. GNU Emacs.

Ultimately, roughly speaking, the whole text also known as information of some project (i.e. the stuff people will read in the printed PDF) will live within the component files and the representation i.e. document's layout will live within the environment file. The product files are mainly to structure the information/document into logical coherent parts.

Why using a Project Structure?

Well, first of all we already discussed that above. Secondly, because this is very useful since we can reuse parts e.g. the environment which is responsible for the layout — yes, as many others, ConTeXt follows the principle of separating information and representation. Same as with XHTML (Extensible HyperText Markup Language) and CSS (Cascading Style Sheets).

Helper Script

I found a nice little helper script on the net which eases things a lot

#!/usr/bin/perl -w
use warnings;
print "Make ConTeXt project -- 2002-05-17\n";
print "copyleft 2002 Henning Hraban Ramm\n";
print "Thankfully adopted by Markus Gattol, Mai 2008\n\n";


@Level       = ("environment", "project", "product", "component");
@Prefix      = ("envi_", "proj_", "prod_", "comp_"); # file prefixes
$Suffix      = ".tex";                               # ending
$IniSuffix   = ".ini";                               # ending for defaults files

$Command     = $ARGV[0];
if (!$Command) {$Command=".";}
$validCommand = 0;
$ProjectPath = ".";     # default path = actual path


if ($Command =~ m/^--/) {               # if first parameter starts with --
        $Command =~ s/^--//;            # delete --
        ($Command eq "help") && help(); # show help, if wanted
        if ($Command =~ m/[0-3]/) { $Command = $Level[$Command]; } # if --0 etc.
        for ($count=@Level-1; $count>0; $count--) { # iterate all levels
                if ($Command eq $Level[$count]) { # if command matches level
                        unless ($ARGV[1]) { # if no second command line parameter
                                my $missname = $Level[$count-1];
                                if ($missname eq $Level[0]) { $missname = $Level[1]; }
                                help("$missname name is missing!");
                        } # if no second parameter
                        if (($count>1) and (!$ARGV[2])) { # with level 2 we need 2 parameters
                                help($Level[$count]." name is missing!");
                        } # if no third parameter
                        $validCommand=1;        # ok, print no help
                        print "making ".$Level[$count]."...\n";
                        MakeFile($count, $ARGV[1], $ARGV[2]);
                } # if
        } # for
        ($Command eq "all") && help("option --all is not yet implemented.\n");
        ($validCommand) && exit(0); # exit without error
} # if --parameter

help("Don't know what to do!"); # help function ends with exit

### END

###
sub MakeFile { # gets level number and two other args (project/product or product/component)
###
        my $ActLev = $_[0];
        my $ProjectName=$_[1];
        my $ProductName=$_[2];
        my $InKey="";
        my $ProjectLine="";
        if ($ProjectName =~ m/^.*[\/\\:]/) { # look for folder delimiters
                $ProjectName = $';      # '
                chop($ProjectPath = $&);
                $ProjectPath =~ tr§\:\/\\§/§;   # change all delimiters to UNIX slashes
        } # if
        if (ProductName =~ m/^.*[\/\\:]/) { # delete other path
                $ProductName = $';      # '
        }
        if (!$ProductName) { $ProductName=$ProjectName; }
        unless (-d $ProjectPath) { # test path
                (-f $ProjectPath) && die "$ProjectPath is a file!\n";
                print("making $ProjectPath...");
                mkdir($ProjectPath) or die "Cannot make dir $ProjectPath: $!";
        } # if no path
        $FileName = $ProjectPath."/".$Prefix[$ActLev].$ProductName.$Suffix;
        (-d $FileName) && die "$FileName is a directory!\n";



# Insert entry in next level file
        if ($ActLev > 1) { # insert product and component into next level
                my @FileList = ();
                my $Count = 0;
                $ProjectFileName = $ProjectPath."/".$Prefix[$ActLev-1].$ProjectName.$Suffix;
                print "Inserting ".$Prefix[$ActLev].$ProductName." into ".$Level[$ActLev-1]." ".$ProjectFileName."...\n";
                open (myFILE, $ProjectFileName) or warn "Cannot open $ProjectFileName: $!";
                while (<myFILE>) {
                        $FileList[$Count] = $_;
                        if (($ActLev==3) && (m/\\project/)) { # if component
                                $ProjectLine = $_;
                        } # if component and project line in product file
                        if (m/\\stop$Level[$ActLev-1]/) { $StopPos = $Count; }
                        if (m/$Prefix[$ActLev]$ProductName/) {
                                $Exist = 1;
                                print "Entry exists already.\n";
                        }
                        $Count++;
                } # while myFILE
                close (myFILE);
                if (!$Exist) {
                        open (myFILE, ">".$ProjectFileName) or warn "Cannot open $ProjectFileName: $!";
                        for ($Count=0; $Count < @FileList; $Count++) {
                                if ($Count == $StopPos) {
                                        print myFILE "\t\\".$Level[$ActLev]." ".$Prefix[$ActLev].$ProductName."\n";
                                } # if StopPos
                                print myFILE $FileList[$Count];
                        } # for
                        close (myFILE);
                }
        } # insert product and component into next level



# Make this level file
        if (-f $FileName) {
                print "$FileName exists. May I overwrite it? (YJ/N, Return)\n";
                while ($InKey !~ m/[JYN]/i) {
                        $InKey= "";
                        print "?";
                        $InKey = getc;
                } # while
        } # if file exists
        $IniFile = $Level[$ActLev].$IniSuffix; # defaults for every level

        if ($InKey !~ m/N/i) {
                print "Making $FileName...\n";
                open (myFILE, ">".$FileName) or die "Cannot make $FileName: $!";

                ($ActLev == 1) && print myFILE "% output=pdf interface=en\n";
                print myFILE "\\start".$Level[$ActLev]." ".$Prefix[$ActLev].$ProductName."\n";
                if (!$ActLev) { $tempLev=1; } else { $tempLev=$ActLev-1; }
                print myFILE "\\$Level[$tempLev] ".$Prefix[$tempLev].$ProjectName."\n";
                ($ProjectLine) && print myFILE $ProjectLine;
                print myFILE "\n";
                if ($ActLev==1) {
                        print myFILE "%  \\showlayout\n";
                        print myFILE "%  \\showgrid\n";
                        print myFILE "%  \\showbodyfontenvironment\n";
                } # if project
                if (-f $IniFile) { # look for .ini file in script dir
                        open (iniFILE, $IniFile) or warn "Cannot open $IniFile: $!";
                        print "inserting $IniFile into $FileName...\n";
                        while (<iniFILE>) { print myFILE;} # while
                        close (iniFILE) or warn "Cannot close $IniFile: $!";
                }
                $IniFile = $ProjectPath."/".$IniFile;
                if ((-f $IniFile) && ($ProjectPath ne ".")) { # look for .ini file in project dir
                        open (iniFILE, $IniFile) or warn "Cannot open $IniFile: $!";
                        print "inserting $IniFile into $FileName...\n";
                        while (<iniFILE>) { print myFILE;} # while
                        close (iniFILE) or warn "Cannot close $IniFile: $!";
                }
                print myFILE "\n";
                print myFILE "\\stop$Level[$ActLev]\n";
                print myFILE "\n";

                close (myFILE) or die "Cannot close $FileName: $!";

        } # if InKey not N
        ($ActLev == 1) && MakeFile(0,$ProjectPath."/".$ProjectName,$ProductName); # project makes environment

} # sub MakeFile



###
sub help {
###
        ($_[0]) && print "ERROR: $_[0]\n\n";
        print "Syntax: makeproject --help\n";
        print "        will give this help\n\n";
        print "......: makeproject --project <projectname>\n";
        print "        will make $Prefix[1]<projectname>$Suffix and $Prefix[0]<projectname>$Suffix\n\n";
        print "......: makeproject --product <projectname> <productname>\n";
        print "        will make $Prefix[2]<productname>$Suffix and add it to $Prefix[1]<projectname>$Suffix\n\n";
        print "......: makeproject --component <productname> <componentname>\n";
        print "        will make $Prefix[3]<componentname>$Suffix and add it to $Prefix[2]<productname>$Suffix\n\n";
#       print "......: makeproject --all <productname>\n";
#       print "        will make all of the files, asks after names\n";
        print "Path should be only in first name!\n";
        exit(1);
} # sub help

After reading and downloading the script called makeproject.pl, we can start creating our new project called The Guide. I was not satisfied with the prefixes created by makeproject.pl in the first place so I made a trivial change to @Prefix = ("envi_", "proj_", "prod_", "comp_"); # file prefixes.

Creating a Project Structure with makeproject.pl

A good start might be to issue the --help switch i.e. ./makeproject.pl --help since it explains what can be done. Then we can actually start using the script.

This should be clear anyway but I better mention it explicitly — our helper script is just what it is, a helper i.e. a project structure can easily be created manually too. All it takes is to create the files and put the correct contents in it (more on that later).

The Project itself

First we create our project.

 1  sa@wks:~/0/context/projects/book$ ll
 2  total 12K
 3  -rwxr-xr-- 1 sa sa 8.3K 2008-04-13 15:45 makeproject.pl
 4  sa@wks:~/0/context/projects/book$ ./makeproject.pl --project book
 5  Make ConTeXt project -- 2002-05-17
 6  copyleft 2002 Henning Hraban Ramm
 7
 8  Thankfully adopted by Markus Gattol, Mai 2008
 9
10  making project...
11  Making ./proj_book.tex...
12  Making ./envi_book.tex...
13  sa@wks:~/0/context/projects/book$ ll
14  total 20K
15  -rw-r--r-- 1 sa sa   77 2008-04-14 10:50 envi_book.tex
16  -rwxr-xr-- 1 sa sa 8.3K 2008-04-13 15:45 makeproject.pl
17  -rw-r--r-- 1 sa sa  155 2008-04-14 10:50 proj_book.tex

We issue line 1 just to see that our script (makeproject.pl) is the only thing in our directory. ll is an alias in my .bashrc. Line 4 creates a project called book. What we get is an environment file (line 15) and the project file (line 17). Now we need one or more products.

Any Project has its Product(s)

The creation of a few is show below. At this point I already tend to stick to the structure from phase 1 from above i.e. I am going to create the following products:

• Endpaper
• Front matter
• Body matter
• Back matter

18  sa@wks:~/0/context/projects/book$ ./makeproject.pl --product book endpaper
19  Make ConTeXt project -- 2002-05-17
20  copyleft 2002 Henning Hraban Ramm
21
22  Thankfully adopted by Markus Gattol, Mai 2008
23
24  making product...
25  Inserting prod_endpaper into project ./proj_book.tex...
26  Making ./prod_endpaper.tex...
27  sa@wks:~/0/context/projects/book$ ./makeproject.pl --product book front_matter
28  Make ConTeXt project -- 2002-05-17
29  copyleft 2002 Henning Hraban Ramm
30
31  Thankfully adopted by Markus Gattol, Mai 2008
32
33  making product...
34  Inserting prod_front_matter into project ./proj_book.tex...
35  Making ./prod_front_matter.tex...
36  sa@wks:~/0/context/projects/book$ ./makeproject.pl --product book body_matter
37  Make ConTeXt project -- 2002-05-17
38  copyleft 2002 Henning Hraban Ramm
39
40  Thankfully adopted by Markus Gattol, Mai 2008
41
42  making product...
43  Inserting prod_body_matter into project ./proj_book.tex...
44  Making ./prod_body_matter.tex...
45  sa@wks:~/0/context/projects/book$ ./makeproject.pl --product book back_matter
46  Make ConTeXt project -- 2002-05-17
47  copyleft 2002 Henning Hraban Ramm
48
49  Thankfully adopted by Markus Gattol, Mai 2008
50
51  making product...
52  Inserting prod_back_matter into project ./proj_book.tex...
53  Making ./prod_back_matter.tex...

Nothing special in lines 18 to 53. I just created all the afore mentioned products, reflecting what we learned during phase 1.

63  sa@wks:~/0/context/projects/book$ ll
64  total 40K
65  -rw-r--r-- 1 sa sa   77 2008-04-14 10:50 envi_book.tex
66  -rwxr-xr-- 1 sa sa 8.3K 2008-04-13 15:45 makeproject.pl
67  -rw-r--r-- 1 sa sa   71 2008-04-14 11:02 prod_back_matter.tex
68  -rw-r--r-- 1 sa sa   71 2008-04-14 11:02 prod_body_matter.tex
69  -rw-r--r-- 1 sa sa   68 2008-04-14 11:02 prod_endpaper.tex
70  -rw-r--r-- 1 sa sa   72 2008-04-14 11:02 prod_front_matter.tex
71  -rw-r--r-- 1 sa sa  293 2008-04-14 11:02 proj_book.tex

The outcome can be seen in lines 65 to 71. All the products we just created have the prefix prod_ in their name. envi_ is the environment file and proj_ is the main project file. Let us take a look at its contents (I used Dired but one could of course use the CLI (Command Line Interface) or a GUI (Graphical User Interface) file browser respectively Editor):

As we can see, we got all our products listed nicely

\product prod_endpaper
\product prod_front_matter
\product prod_body_matter
\product prod_back_matter

Even if we might figure later one that maybe even a product is not needed at all we can either edit the files to remove its entry or just leave it as it is since it would not cause any problems at all. For example, one could use exactly this setup to create a flyer — he would then just create a single component within prod_body_matter and be fine even though he has all the other prod_ files lying around.

Products consist of Components

Now that we have created a logical structure for the information/document, we can break down things into even smaller logical units that can then used to fill them with ConTeXt source code in order to get processed and turned into awesome-looking output e.g. PDF (Portable Document Format).

First of all we need a front cover. As we already know from phase 2, the front cover belongs to the front matter product i.e. prod_front_matter. We are now going to create comp_front_cover — the component that will contain the front cover source code in the future.

73  sa@wks:~/0/context/projects/book$ ./makeproject.pl --component front_matter front_cover
74  Make ConTeXt project -- 2002-05-17
75  copyleft 2002 Henning Hraban Ramm
76
77  Thankfully adopted by Markus Gattol, Mai 2008
78
79  making component...
80  Inserting comp_front_cover into product ./prod_front_matter.tex...
81  Making ./comp_front_cover.tex...

To show the result of the just taken action in line 73 we use ll again which we remember is an alias in my .bashrc as can be seen. In line 85 further down we see what resulted from the command in line 73 — we got our new component called comp_front_cover.

sa@wks:~/0/context/projects/book$ type ll
ll is aliased to `ls -lh'
sa@wks:~/0/context/projects/book$

82   sa@wks:~/0/context/projects/book$ ll
83   total 48K
85  -rw-r--r-- 1 sa sa  106 2008-04-14 12:20 comp_front_cover.tex
86  -rw-r--r-- 1 sa sa   77 2008-04-14 10:50 envi_book.tex
87  -rwxr-xr-- 1 sa sa 8.3K 2008-04-13 15:45 makeproject.pl
88  -rw-r--r-- 1 sa sa   71 2008-04-14 11:02 prod_back_matter.tex
89  -rw-r--r-- 1 sa sa   71 2008-04-14 11:02 prod_body_matter.tex
90  -rw-r--r-- 1 sa sa   68 2008-04-14 11:02 prod_endpaper.tex
91  -rw-r--r-- 1 sa sa   72 2008-04-14 11:02 prod_front_matter.tex
92  -rw-r--r-- 1 sa sa  293 2008-04-14 11:02 proj_book.tex
93  sa@wks:~/0/context/projects/book$

I showed how it works — It being how to start with some random ConTeXt project by creating a structure (see phase 3). I am not going to show how to create any component listed within the phase 1 part from above except for one i.e. comp_front_cover.tex. However, the contents of prod_front_matter after all front matter components have been created can be seen in the upper left corner of the first image below.

The attentive reader might also spot that there is one component more than those are listed in phase 2 during step 2 — namely comp_meta_data. I use this component for meta data like variables and the like. I put some explanatory content into it as can be seen on the right hand side of the first image below (middle window). Those variables can then be used across the whole project (i.e. book in our case) which eases things a lot and avoids tedious typing the same things over and over again.

The second image below shows how I use the contents of comp_meta_data in comp_front_cover (lower right window). Finally, the third picture shows the resulting PDF (Portable Document Format) file viewed with acroread on DebianGNU/Linux after compiling the whole project book.

Since I use mighty GNU Emacs, compiling and viewing is a piece of cake. With the AucTeX setup from my .emacs all I need to do is hit C-c C-c RET. More on that in the GNU Info manual section (Info-goto-node "(auctex) Commands").

,----[ C-h k C-c C-c ]
| C-c C-c runs the command TeX-command-master, which is an interactive
| compiled Lisp function in
| `/usr/share/emacs-snapshot/site-lisp/auctex/tex-buf.elc'.
|
| It is bound to C-c C-c.
| (TeX-command-master &optional override-confirm)
|
| Run command on the current document.
|
| If a prefix argument override-confirm is given, confirmation will
| depend on it being positive instead of the entry in `TeX-command-list'.
`----

One should have gotten the idea by now and thus be able to follow my examples for his/her project. Anyway, now would be the perfect moment to read chapter 2 from one of the ConTeXt manuals.

Layout

The layout is the one thing where most folks draw their attention to first — overlooking the structure. Clearly, that is the wrong sequence.

First comes structure then comes layout and only after those two initial steps comes the task of writing — which might include all kinds of stuff like e.g. travelling to Brazil in order to make some photography that goes into the document, visiting the library for recherche, running dozens of tests in the chemistry laboratory or spending dozens of hours staring at some sheet of paper trying to figure some mathematics.

The alerted reader might already sense it... We start writing things down from the very beginning. Only beginners think they can research/work on something for a few weeks (or maybe years) and then, at the end, sit down and write about it... not going to work! Any professor etc. will tell you the same — we start taking notes respectively writing things down from the very beginning. Otherwise information gets lost — humans forget, imagine... — and thus the writing will always be of lower quality simply because it lacks facts. Second to that, maybe not true for master theses and even less complex things but certainly for stuff from master theses upwards: Humans are incapable of structuring very complex stuff and think/write about it in parallel. Again a fact and yes, I also learned the hard way although advised otherwise by betters before.

Because it is so damn important we go into round three: Students always give good examples. If you one you are up to writing your master thesis or something akin and you think you work along for ~6 months or so before you start writing things down... Well, your thesis is going to be crap. Plain and simple. What works best is a combination of three things — working/research, writing and for example sitting on a bench nearby the pond, getting the big picture. If you cycle through those three steps over and over again then what you get is a process leading to the delivery of a successful thesis. Also let folks take a look at your writings from the beginning for reasons of scrutiny — ignore the dump comments and thrive on the valuable ones (even if very critic about your work; those are the most valuable ones anyway). I am getting off-topic here... ;-]

From my practical experience it just makes sense to take care about the structure before the layout. For one we know more about the issue after thinking about the structure and therefore we can find a more appropriate layout. Secondly during the process of structuring we might already get some layout parts for free e.g. some image for the front cover.

Front / Back Cover

What we want is to create a front and back cover page using ConTeXt.

Typography

Page Layout

Miscellaneous

Useful Commands

\headnumber
\currentheadnumber