Difference between revisions of "Project structure"

From Wiki
Jump to navigation Jump to search
(corrected some spellings and emphasis, added link)
(25 intermediate revisions by 14 users not shown)
Line 1: Line 1:
< [[The ConTeXt Way]]
+
=Introduction=
  
ConTeXt knows no document classes (as LaTeX does). You can define your layout yourself. If you use the same layout for several projects, save it as an '''environment''' file.
+
ConTeXt knows no document classes (as LaTeX does). You can define your [[Layout|layout]] yourself.  
  
How to split up a large project, say a book, in several handy parts? – Use ConTeXt's project management facilities.
 
  
* a '''project''' contains one ore more '''products'''
+
:<i><b>Note</b>: the project structure explained on this page is not the only way to handle complex documents. If you are working on a project with a single output file, it may be simpler to use {{cmd|startdocument}} (perhaps in combination with {{cmd|usemodule}} or {{cmd|environment}} and {{cmd|startcomponent}} as explained below) and ignore the elaborate project and product setups.</i>
 +
 
 +
 
 +
If you use the same layout for several related products, it may make sense to use the project support in ConTeXt. You then save your layout settings as an '''environment''' file, and you can reuse various document parts in multiple products.
 +
 
 +
How to split up a large project, say a collection of books, in several handy parts? – Use ConTeXt's project management facilities.
 +
 
 +
* a '''project''' links one or more '''products''' to their environment
 
* a '''product''' contains several '''component'''s
 
* a '''product''' contains several '''component'''s
 
* an '''environment''' defines the common layout (etc.) of a project
 
* an '''environment''' defines the common layout (etc.) of a project
  
The environment could also contain different versions ([[Modes]]) of the layout, e.g. print and screen (like Pragma's manuals) or final and correction etc.
+
The environment could also contain [[Modes|different versions]] of the layout, e.g. print and screen (like Pragma's manuals) or final and correction etc.
  
 
Example 1: Magazine
 
Example 1: Magazine
 
* project: magazine
 
* project: magazine
 
* product: one volume of the magazine
 
* product: one volume of the magazine
* component: an single article
+
* component: a single article
  
 
Example 2: Book
 
Example 2: Book
* project: book
+
* project: a series of books
* product: part of the book
+
* product: one book
* component: chapter
+
* component: part or chapter
 +
 
 +
[[Image: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 {{cmd|product}} (e.g. table of content, sectioning commands, text, {{cmd|component}} etc.). So all the things on project level have to be put inside a {{cmd|product}}, otherwise they will show up in the individual components (or products), too. That also makes it problematic to use {{cmd|component}} directly inside a project file, i.e. you '''have''' to use {{cmd|product}}, you can't skip it.
 +
 
 +
While you can compile ("tex") products and single components, the project is not intended for compiling; trying might lead to infinite inclusion loops and the error message "TeX capacity exceeded".
 +
 
 +
=File and directory setup=
 +
 
 +
==Naming conventions==
  
If you tex (compile) one single component (e.g. a chapter of a book) or product (e.g. one volume of a magazine), the settings of the project's environment are used.
+
[[User:Hraban|Hraban]] uses and suggests the following naming conventions
[[User:Hraban|Hraban]] uses the following naming conventions
 
 
* project_foo
 
* project_foo
 
* prd_foo
 
* prd_foo
 
* c_foo
 
* c_foo
 
* env_foo
 
* env_foo
 +
 +
There's a Python script <tt>contextproject.py</tt> at Hraban's [http://github.com/fiee/tools/blob/master/contextproject.py 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'''
 
'''Project'''
<pre>
+
<texcode>
 
\startproject project_mymag
 
\startproject project_mymag
 
\environment env_mymag % only mentioned here!
 
\environment env_mymag % only mentioned here!
Line 37: Line 58:
 
\product prd_year2004-03
 
\product prd_year2004-03
 
\product prd_year2004-04
 
\product prd_year2004-04
 
\completetableofcontents
 
  
 
\stopproject
 
\stopproject
</pre>
+
</texcode>
  
 
'''Environment'''
 
'''Environment'''
<pre>
+
<texcode>
 
\startenvironment env_mymag
 
\startenvironment env_mymag
  
Line 51: Line 70:
  
 
\stopenvironment
 
\stopenvironment
</pre>
+
</texcode>
  
 
'''Product'''
 
'''Product'''
<pre>
+
<texcode>
 
\startproduct prd_year2004-01
 
\startproduct prd_year2004-01
 
\project project_mymag
 
\project project_mymag
Line 64: Line 83:
  
 
\stopproduct
 
\stopproduct
</pre>
+
</texcode>
  
 
'''Component'''
 
'''Component'''
<pre>
+
<texcode>
 
\startcomponent c_editorial
 
\startcomponent c_editorial
 
\product prd_year2004-01 % but you can use it in other products anyway
 
\product prd_year2004-01 % but you can use it in other products anyway
\project project_mymag
 
  
 
\title{Editorial}
 
\title{Editorial}
Line 77: Line 95:
  
 
\stopcomponent
 
\stopcomponent
</pre>
+
</texcode>
 +
 
 +
==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'''
 +
<texcode>
 +
\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
 +
</texcode>
 +
 
 +
'''Product'''
 +
<texcode>
 +
\startproduct prd_issue2011-01
 +
\project project_mymag
 +
\environment env_mymag
 +
 
 +
\component c_editorial
 +
\component c_article1
 +
...
 +
 
 +
\stopproduct
 +
</texcode>
 +
 
 +
ConTeXt automatically looks into parent directories.
 +
 
 +
=Command behaviour=
 +
 
 +
Within a <code>\start...\stop...</code> 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 <code>\component</code> inside a <code>\startenvironment</code> block. The table below gives an overview.
 +
 
 +
{|
 +
|                          || {{cmd|project}} || {{cmd|environment}} || {{cmd|product}} || {{cmd|component}}
 +
|-
 +
| {{cmd|starttext}}        || &mdash;        || once                || &mdash;        || at every mention               
 +
|-
 +
| {{cmd|startproject}}    || &mdash;        || once                || once            || &mdash;               
 +
|-
 +
| {{cmd|startenvironment}} || &mdash;        || once                || &mdash;        || &mdash;               
 +
|-
 +
| {{cmd|startproduct}}    || once            || once                || &mdash;        || at every mention               
 +
|-
 +
| {{cmd|startcomponent}}  || once            || once                || &mdash;        || at every mention               
 +
|}
 +
 
 +
=See also=
 +
 
 +
Hans Hagen (2011) [http://pragma-ade.com/general/magazines/mag-1101.pdf Project Structure], ConTeXt magazine #1101.
 +
 
  
There's a Perl script <tt>makeproject.pl</tt> at Hraban's site [http://www.ramm.ch/fiee/texnique/?menu=0-1-3&lang=en ''fiëé teXnique''] to help creating the files (.ini files can be used for initial content).
+
[[Category:Basics]]
 +
[[Category:Tools]]

Revision as of 11:08, 10 September 2020

Introduction

ConTeXt knows no document classes (as LaTeX does). You can define your layout yourself.


Note: the project structure explained on this page is not the only way to handle complex documents. If you are working on a project with a single output file, it may be simpler to use \startdocument (perhaps in combination with \usemodule or \environment and \startcomponent as explained below) and ignore the elaborate project and product setups.


If you use the same layout for several related products, it may make sense to use the project support in ConTeXt. You then save your layout settings as an environment file, and you can reuse various document parts in multiple products.

How to split up a large project, say a collection of books, 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.

While you can compile ("tex") products and single components, the project is not intended for compiling; trying might lead to infinite inclusion loops and the error message "TeX capacity exceeded".

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

\startproject project_mymag
\environment env_mymag % only mentioned here!

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

\stopproject

Environment

\startenvironment env_mymag

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

\stopenvironment

Product

\startproduct prd_year2004-01
\project project_mymag

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

\stopproduct

Component

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

\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.