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 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.)
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.
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:
- 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.
- For a more ambitious proposal for dealing with index pages, see AdminCookbookViews?.]
IncludingSourceCode is a topic unto itself.
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?)
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
