e r l a n g : c o o k b o o k

/ WebHome / CookbookForm / TopicType / SectionIndex / CookbookStructure / Erlang.ChapterStructure

This Web


WebHome 
WebChanges 
TOC
NewRecipe 
WebTopicList 
WebStatistics 

All Webs


Chicken
Cookbook
Erlang
Know
Main
Plugins
Sandbox
Scm
TWiki  

Erlang Links


Erlang.org
Erlang Wiki
ErlMan
Erlang Wiki
The Jungerl
Erlang-fr.org
Joe Armstrong
Lambda the Ultimate

Erlang Web Ring


[Prev]: Joe Armstrong's Page
[Next]: Joe Armstrong's Page

Cookbook Chapter Structure

Introduction

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

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.

Introduction Section

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

Recipe Section

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

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

Comments Section

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.

-- BrentAFulgham - 18 Aug 2004

 
 
Copyright © 2004 by the contributing authors. All material on the Erlang Cookbook web site is the property of the contributing authors.
This material can be redistributed and/or modified under the terms of the GNU Lesser General Public License (LGPL), version 2.1, as published by the Free Software Foundation.
Ideas, requests, problems regarding Schematics Cookbook? Send feedback.
/ You are Main.guest