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

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

This Web


All Webs


Erlang Links

Erlang Wiki
Erlang Wiki
The Jungerl
Joe Armstrong
Lambda the Ultimate

Erlang Web Ring

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

Cookbook Structure Proposal


Below is the proposal for the new cookbook structure, written prior to implementation. The technical details of the final design are described at ChapterStructure. Although the proposal below provides more background information, the details in ChapterStructure supersede the details below. The below will be updated and converted to documentation. SiteToDo?.


This proposal is a relatively minor extension to the existing approach.

The proposed change centers around the structure of chapters. Currently, chapters are manually-edited topics. This proposal would change that, to allow chapters to be auto-generated by a simple query, and to better support automatic generation of various high-level views of the cookbook, such as TOCs.

To achieve this, a chapter will be defined as consisting of a number of sections, i.e. separate topics with a TopicType of Section. Generation of a chapter will be achieved simply by appending its sections together using a query and the %INCLUDE% directive. It will be required that chapter topics themselves are autogenerated, and contain no other content than the chapter title, and the query which includes its sections.

Requiring that chapters consist of sections which are stored in separate topics allows greater control over autogenerated views of the cookbook, and allows things to be done with TWiki searches that wouldn't otherwise work correctly. It allows queries to choose whether they want to work with sections, or chapters, or both. This is not possible if chapter topics are arbitrarily-constructed collections of content, such as a mix of headings at different levels and the use of %TOC% directives.

Note that a major factor driving the design of this proposal is, of course, the features and limitations of TWiki. However, the proposal is a simple one which would not be inappropriate in other contexts, outside of TWiki, and the structural rules it imposes should aid in management of the cookbook. It can be thought of as a kind of relational normalization of topic content: ensuring that content from different levels (chapters and sections) is not mixed.


Examples of chapters which have been changed to work this way are StringChapter and NumberChapter (follow the links to take a look). The entire source to StringChapter now looks like this:

---+ %URLPARAM{"title"}%


<br />

   * Set ALLOWTOPICCHANGE = Main.SchematicsEditorsGroup

(The previous manually-generated StringChapter topic can be found in StringRecipesOld?.)

StringChapter consists of four section topics, and a special "Comments" section, StringChapterComments?. The normal section topics are:

The query which generates the StringChapter page simply searches for all the Sections whose parent is the current chapter, and %INCLUDE%s them all into the chapter topic. Contributors can add sections to a chapter at will, simply by setting TopicType to Section and setting ParentTopic accordingly. This means that contributors only have to concern themselves with actual content, not with overall structure, other than classifying the topics they work on correctly.

A section can contain anything which makes sense when %INCLUDE%d at the chapter level. Most chapters will have a recipe section. The recipe section can also be automatically generated. StringRecipes is an example of this. It is based on the following query:

casesensitive="on" regex="on" nosearch="on" nototal="on" order="formfield(TopicOrder)" 


Chapter topics will now be auto-generated, as will sections containing lists of recipes. Various TOC-generating queries will become easier and produce better results. Examples of this include the new TOC and SectionIndex. This should completely eliminate the need for a manually-edited TOC, like OldTOC?. Previous attempts at automating the TOC had various shortcomings.

In general, this proposal better supports multiple views of the cookbook. Further explanation is provided in the following section.

Explanation of Design Features

The proposed approach addresses various problems which may not be immediately obvious. Analyzing the structure of the SectionIndex topic will help focus on the important aspects of this proposal.

The SectionIndex topic provides a view of the cookbook in which each chapter has its own heading, rather than being bulleted items as in the case of TOC (automatically generated) or OldTOC? (semi-manually created). Although SectionIndex doesn't currently appear in final form, since the underlying topics are not yet appropriately arranged, something similar to the desired effect can be seen in RecipeIndex. RecipeIndex, however, simply provides a list of recipes for each chapter, and does not reflect any other structure of those chapters.

To achieve the effect desired for SectionIndex, it uses a nested search query, which queries first for Chapters, and within each chapter, for Sections. Each Section, in turn, has its contents formatted using the %TOC% directive. This provides the ability to render chapter headings as major headings, while rendering section contents in TWiki's bulleted TOC format.

If section content - actual section headings and text - were directly present in a chapter topic, then using %TOC% to summarize this content would also include the chapter heading, which has to be present on the chapter topic. In queries such as the one for SectionIndex described above, this results in duplication of the chapter title, e.g.:

String Recipes

Requiring that chapters consist of sections which are stored in separate topics allows this duplication to be avoided, by working at the appropriate level. As described in the #Overview above, this allows queries to choose whether they want to work with sections, or chapters, or both. This is not possible if chapter topics are arbitrarily-constructed collections of content, such as a mix of headings at different levels and the use of %TOC% directives.

Ordering of chapters, sections, and recipes.

To support control over ordering (sequencing) of chapters, sections, and recipes, the current plan, chosen for reasons of expedience, is to sort sibling topics according to the value of the TopicOrder field in the CookbookForm.

Combined with the above proposal, this takes care of an issue which otherwise arises in topics such as RecipeIndex: if sections and recipes are treated as siblings, then to interperse sections and recipes appropriately can require a total ordering on all recipes and sections in a chapter. Currently, RecipeIndex only avoids this problem because existing Section topics all happen to be introductory ones that appear at the beginning of their chapters.

Under the proposal, recipes would appear within a section, not directly at the chapter level. Sections would be sorted according to their TopicOrder. One of these sections would typically contain recipes, but the order of the recipes within the section would have no effect on the order of the sections.

Since there would typically be relatively few sections within a chapter, providing a total ordering on sections within chapters should not be onerous.

Implementation plan

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