s c h e m a t i c s : c o o k b o o k

/ WebHome / Cookbook.AuthorGuide

This Web


WebHome 
WebChanges 
TOC (with recipes)
NewRecipe 
WebTopicList 
WebStatistics 

Other Webs


Chicken
Cookbook
Erlang
Know
Main
Plugins
Sandbox
Scm
TWiki  

Schematics


Schematics Home
Sourceforge Page
SchemeWiki.org
Original Cookbook
RSS

Scheme Links


Schemers.org
Scheme FAQ
R5RS
SRFIs
Scheme Cross Reference
PLT Scheme SISC
Scheme48 SCM
MIT Scheme scsh
JScheme Kawa
Chicken Guile
Bigloo Tiny
Gambit LispMe
GaucheChez

Lambda the Ultimate
TWiki.org

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)

Handling PLT Specific-ness

Although the Cookbook is primarily oriented towards PLT Scheme, some care needs to be taken in this area. For more on this subject, see BeingPltSpecific.

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.

-- AntonVanStraaten - 31 Mar 2004

Comments about the Authoring Guide

Added BeingPltSpecific.

-- NeilVanDyke - 11 May 2004

 
 
Copyright © 2004 by the contributing authors. All material on the Schematics Cookbook web site is the property of the contributing authors.
The copyright for certain compilations of material taken from this website is held by the SchematicsEditorsGroup - see ContributorAgreement & LGPL.
Other than such compilations, 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