This is technical documentation of the Cookbook chapter structure. Documentation for authors will be based on the automated creation of chapters via the
NewChapter page - authors don't need to be familiar with the detail below.
Chapters can be created via the
NewChapter page, which uses
DefaultChapterTemplate to create a new chapter. This ensures that a chapter has the proper structure. The source to
DefaultChapterTemplate is as follows:
%STARTINCLUDE%
---+ %URLPARAM{"title"}%
%TMPL:P{"chapterquery"}%
%STOPINCLUDE%
<br />
---
%TMPL:P{"chaptercommentlink"}%
%INCLUDE{"%TOPIC%Comments"}%
* Set ALLOWTOPICCHANGE = Main.SchematicsEditorsGroup
The
chapterquery referenced above is a TWiki query which selects all topics with a
TopicType of
Section or
SectionStub and whose
ParentTopic is the chapter in question. This is typically used to include an Introduction section, a Recipes section, and a Comments section. Other sections can also be included, for example a References section, or an Other Recipes section. No change needs to be made to the above chapter source to achieve this; it's all based on the values specified in the
CookbookForm for the topics in question.
The standard Introduction, Recipe and Comments sections are described below.
This is an "ordinary", un-automated section, which simply contains introductory text for the chapter in question. It will typically have a format like the following:
%STARTINCLUDE%
---++ Introduction
Froobnitzen are an advanced feature of Scheme which allows Scheme
programs and their users to generate and travel through arbitrary
wormholes in spacetime. This chapter will show you how to use
froobnitzen, and how to avoid accidentally destroying your planet
of residence in the process. Needless to say, we at Schematics
disclaim all responsibility for the consequences if you choose to
use froobnitzen in your programs...
%STOPINCLUDE%
-- Main.SpaceCowboySchemer - 13 Jun 2077
Most chapters have a Recipes section. Recipe sections should have a
TopicType of
Section, and their parent topic should be the chapter they are part of. Their
TopicOrder should be set to a value which causes them to appear after any Introduction section - the typical value is
020.
All recipe sections should have the following source:
%STARTINCLUDE%
---++ Recipes
%TMPL:P{"recipequery"}%
%STOPINCLUDE%
<br />
---
* Set ALLOWTOPICCHANGE = Main.SchematicsEditorsGroup
These Recipe topics are not currently created automatically, but they should be, and will be when chapter creation is fully automated.
The
recipequery referenced above is a TWiki query which selects all topics with a
TopicType of
Recipe or
RecipeStub and whose
ParentTopic is the chapter in question.
Recipes themselves should be created via the
NewRecipe page. They should have a
TopicType of
Recipe or
RecipeStub, and their
ParentTopic should be the Recipe
Section, not the chapter topic. The
TopicOrder of a Recipe will determine the order in which it appears in the list of recipes. It is often the case that simpler, more basic recipes should appear before other recipes, and
TopicOrder can be used to achieve this. Recipes created via the
NewRecipe page
Chapters should have a comments section for author comments and discussion, which is not considered part of the cookbook content. The comment sections are not included by the chapter's section query, since they do not form part of the cookbook content and shouldn't appear e.g. in tables of contents. Instead, the chapter comments section is included based on a naming convention, using the chapter's topic name with the word
Comments appended, which results in a topic name such as XxxChapterComments. This naming convention is required simply because the default chapter template uses the directive
%INCLUDE{"%TOPIC%Comments"}% to include the comments section.
Chapter comment topics must have a
TopicType of
Comment. The parent topic should be the chapter they belong to. The
TopicOrder doesn't matter, and can be left blank, since there is only one comments section per chapter and it is included explicitly at the correct point in the chapter.
Comment sections should be created with the following source:
%TMPL:P{"chaptercommenttip"}%
%STARTINCLUDE%
---++!! Comments
%STOPINCLUDE%
Once chapter creation is fully automated, these comment topics will be created automatically when a chapter is created.
--
AntonVanStraaten - 14 Jun 2004
RSS