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

/ WebHome / Erlang.AuthorGuide

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

This topic is under construction, now that we have a good sense of how the cookbook should be structured with Twiki.

Topics that will be covered here include:

...plus the other material already found below. As working examples, see pages like TOC, StringChapter, and the topics linked from StringChapter.

The current proposed structure for the cookbook is as follows - nothing is final, poke holes at will.

Recipes

Recipes are the basic unit of content in the cookbook. Each recipe should usually have its own TWiki topic (page). In some cases, it may make sense to use a single topic for a series of short, related recipes. Recipes are combined into larger units, such as sections or chapters, as described above.

To create a new recipe, please use the NewRecipe page. This will generate a new page based on a standard template for recipes.

To support referencing by higher-level topics, the heading in a recipe topic should not be a top-level heading - it should be a 2nd-level heading (---++) or lower, depending on the level at which it is to be included. For example, if a recipe is to appear within a section, the section would have a second-level heading, and the recipe topic would begin with a 3rd-level heading.

(It would be nice if the toc & inclusion mechanisms automatically made headings relative to the page in which they're included, but Twiki doesn't seem to support that at present.)

Chapters, Sections, and Subsections.

A chapter is a Twiki topic which uses TWiki's %TOC% and/or %INCLUDE% tags to reference other topics, such as individual recipes. Chapter headings are top-level headings, using the TWiki ---+ tag. Section headings are 2nd-level, subsections are 3rd-level, etc.

Multi-level inclusion is possible, so if necessary, a hierarchy of included topics from chapters to sections to subsections to recipes, as appropriate, can be used.

Index Pages

Some topics, such as chapters and sections, will simply be lists of links to other topics. These can be constructed using the %TOC% tag. This automatically pulls in the headings from the specified topic, up to an optionally specified depth. This allows changes to headings in the referenced topics to automatically be propagated to any & all parent topics. Here's an example of the necessary markup:

---++ Strings & Things
%TOC{"SuperStrings")}%
%TOC{"SillyString")}%

[Technical notes:

  1. This approach creates, at the HTML level, multiple separate bullet lists, each using the HTML UL element. The end result looks OK (example: TOC), and it should be easy enough to merge such lists for e.g. print publishing purposes.
  2. For a more ambitious proposal for dealing with index pages, see AdminCookbookViews?.]

Source Code

IncludingSourceCode is a topic unto itself.

Tying it Together

New recipes should be added to the appropriate index page using the %TOC% tag, as shown in the Index Pages section above. If a new index page is created, then it should be added to the TOC topic. That topic simply consists of a %TOC% statement for each index page.

Soon, we hope to be able to generate various alternative views of the cookbook content, such as entire chapters combined into a single page. (Work in progress; see AdminCookbookViews?)

Commenting on Cookbook Topics

To attach comments to a cookbook topic so that the comments will not appear in the final book, use the %STARTINCLUDE% and %STOPINCLUDE% tags to delimit the part of a topic that belongs to the book. Any text outside that topic will not be included in higher-level pages.

Recipes created via the NewRecipe page automatically include the above tags.

-- BrentAFulgham - 18 Aug 2004

Comments about the Authoring Guide

 
 
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