Difference between revisions of "Project structure"
(added subtitles) |
(Example for directory tree setup) |
||
Line 29: | Line 29: | ||
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</cmd> (e.g. table of content, sectioning commands, text, <cmd>component</cmd> etc.). So all the things on project level have to be put inside a <cmd>product</cmd>, otherwise they will show up in the individual components (or products), too. That also makes it problematic to use <cmd>component</cmd> directly inside a project file, i.e. you have to use <cmd>product</cmd>, you can't skip it. | 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</cmd> (e.g. table of content, sectioning commands, text, <cmd>component</cmd> etc.). So all the things on project level have to be put inside a <cmd>product</cmd>, otherwise they will show up in the individual components (or products), too. That also makes it problematic to use <cmd>component</cmd> directly inside a project file, i.e. you have to use <cmd>product</cmd>, you can't skip it. | ||
− | ==Naming conventions== | + | ==File and directory setup== |
+ | |||
+ | ===Naming conventions=== | ||
[[User:Hraban|Hraban]] uses and suggests the following naming conventions | [[User:Hraban|Hraban]] uses and suggests the following naming conventions | ||
Line 39: | Line 41: | ||
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... | 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== | + | ===Example files=== |
'''Project''' | '''Project''' | ||
Line 92: | Line 94: | ||
</texcode> | </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> | ||
+ | |||
+ | (This is untested. I assume that ConTeXt looks automatically into parent directories.) | ||
+ | |||
+ | ==Command behaviour== | ||
Depending on the (start-stop) environment a command will either load a file once, or many times or not at all. The following table specifies what happens when: | Depending on the (start-stop) environment a command will either load a file once, or many times or not at all. The following table specifies what happens when: |
Revision as of 08:51, 12 August 2011
< The ConTeXt Way | Structurals >
Contents
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
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
\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 \product tableofcontent \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 \project project_mymag \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
(This is untested. I assume that ConTeXt looks automatically into parent directories.)
Command behaviour
Depending on the (start-stop) environment a command will either load a file once, or many times or not at all. The following table specifies what happens when:
\project | \environment | \product | \component | |
\starttext | once | once | once | many |
\startproject | once | none | once | none |
\startenvironment | once | none | once | none |
\startproduct | once | once | once | none |
\startcomponent | once | once | once | none |