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:
%STARTINCLUDE%
---+ %URLPARAM{"title"}%
%TMPL:P{"chapterquery"}%
%STOPINCLUDE%
<br />
---
%TMPL:P{"chaptercommentlink"}%
%INCLUDE{"%TOPIC%Comments"}%
* 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:
%SEARCH{"TopicType.*value=\"Recipe;ParentTopic.*value=\"%TOPIC%"
casesensitive="on" regex="on" nosearch="on" nototal="on" order="formfield(TopicOrder)"
format="%TMPL:P{"recipefmt"}%"}%
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.
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.:
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.
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.
- Split existing chapters into sections
- Archive existing chapter topics
- Replace chapter topics with query-based versions
- Profit!
--
BrentAFulgham - 18 Aug 2004
