Project structure

< The ConTeXt Way | Structurals >

Contents [hide]
1 Introduction
2 File and directory setup
2.1 Naming conventions
2.2 Example files
2.3 Subdirectories
3 Command behaviour
4 See also
Introduction

ConTeXt knows no document classes (as LaTeX does). You can define your layout
yourself. If you use the same layout for several products, save it as an
environment file.
How to split up a large project, say a book, in several handy parts? � Use
ConTeXt's project management facilities.
a project links one or more products to their environment
a product contains several components
an environment defines the common layout (etc.) of a project
The environment could also contain different versions of the layout, e.g. print and
screen (like Pragma's manuals) or final and correction etc.
Example 1: Magazine
project: magazine
product: one volume of the magazine
component: a single article
Example 2: Book
project: a series of books
product: one book
component: part or chapter
Project-structure.png
If you tex (compile) one single component (e.g. a chapter of a book) or product
(e.g. one volume of a magazine), the environment file of the project is used.
In addition, you have to keep in mind that when compiling a product or component
file, ConTeXt goes "up" to the project file and compiles everything it finds in
there that is not a \product (e.g. table of content, sectioning commands, text,
\component etc.). So all the things on project level have to be put inside a
\product, otherwise they will show up in the individual components (or products),
too. That also makes it problematic to use \component directly inside a project
file, i.e. you have to use \product, you can't skip it.
File and directory setup

Naming conventions
Hraban uses and suggests the following naming conventions
project_foo
prd_foo
c_foo
env_foo
There's a Python script contextproject.py at Hraban's github repository to help
creating the files (.ini files can be used for initial content). This functionality
would be nice to be integrated in any editor supporting ConTeXt...
Example files
Project
\environment env_mymag % only mentioned here!
\startproject project_mymag

\product prd_year2004-01
\product prd_year2004-02
\product prd_year2004-03
\product prd_year2004-04

\product tableofcontent

\stopproject
Environment
\startenvironment env_mymag

\setuplayout[...]
% all setups...

\stopenvironment
Product
\project project_mymag
\startproduct prd_year2004-01

\component c_editorial
\component c_article01
\component c_article_by_me
% ...

\stopproduct
Component

\project project_mymag
\product prd_year2004-01 % but you can use it in other products anyway
\startcomponent c_editorial

\title{Editorial}

Dear reader...

\stopcomponent
Subdirectories
If you keep all files in one directory, it tends to get confusing. Here�s a
structured example where we keep all parts of one product together:
env_mymag.tex
project_mymag.tex
2011-01/prd_issue2011-01.tex
2011-02/prd_issue2011-02.tex
2011-03/prd_issue2011-03.tex
...
2011-03/c_editorial.tex
2011-03/c_article1.tex
...
2011-03/img/author1.jpg
...
general_img/logo.pdf
...
Environment
\startenvironment env_mymag
\project project_mymag

...

% where \product and \component look for TeX input files

\usepath[{2011-01,2011-02,2011-03}]

% where to look for images

\doifmodeelse{*product}
{\setupexternalfigures[directory={../general_img}]}
{\setupexternalfigures[directory={../general_img, img}]}

...
\stopenvironment
Product
\startproduct prd_issue2011-01
\project project_mymag
\environment env_mymag

\component c_editorial
\component c_article1
...

\stopproduct
ConTeXt automatically looks into parent directories.
Command behaviour

Within a \start...\stop... environment, project, product, and environment

definition files are loaded only once, while component files are loaded at every
mention. In addition, certain loading commands are ignored inside certain
environments -- for example, it makes no sense to load a \component inside a
\startenvironment block. The table below gives an overview.
\project \environment \product \component
\starttext � once � at every mention
\startproject � once once �
\startenvironment � once � �
\startproduct once once � at every mention
\startcomponent once once � at every mention
See also

Hans Hagen (2011) Project Structure, ConTEXt magazine #1101.