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

/ WebHome / Cookbook.AdminCookbookViews

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

Supporting Multiple Views of the Cookbook

At a minimum, we want to be able to support two "views" of the cookbook - one which supports online browsing well, and another which supports generation of a document format such as PDF, possibly for print publishing. For various reasons, a single layout doesn't fully address the needs of both of these views.

TWiki itself is not particularly oriented to supporting such alternate views. It is possible do something along these lines using topic inclusion and the table of contents feature, but these mechanisms have various rather arbitrary limitations, and have proved less than ideal in implementing the exact structure desired for even a single view, let alone two or more.

I think this situation can be addressed more to our liking without too much work. A solution could be implemented by defining index pages, such as StringRecipes, using a metadata format of our own, which could be as simple as a list of topic names with perhaps some minimal associated structure information.

Given a metadata description of an index page, a script implemented either in TWiki's native Perl or in Scheme (as has been done with CodeFormatting), could read this list and present it in various ways that are specifically designed to support what's wanted for the Cookbook. This would not be a 100% solution, it need only be very specifically oriented to producing the output formats we want for the cookbook. As such, it need not be particularly complex. It could be as simple as generating a TWiki topic with the necessary sequence of %INCLUDE% and %TOC% statements -- this alone could simplify the process of adding new recipes, and would also eliminate the need to duplicate these commands, which would otherwise be necessary to support multiple views.

In addition to addressing the requirement for multiple views of the cookbook, this would have the added benefit of moving cookbook formatting further under programmatic control. This should make it easier to impose a consistent structure on the cookbook. It would also be easy to develop a page which asks a contributor where they want to insert a new recipe, and for the recipe topic name. This topic name would be automatically added to the appropriate index list, and the new topic would be created for the user, with the appropriate parent topic already set.

ToDo: needs fleshing out.

-- AntonVanStraaten - 20 Apr 2004

I feel the main web view should show the structure of the Wiki. That is, links as WikiWords?, no magic TOC etc. This way users can get a feel for how the site is structured just by reading the cookbook, so when they come to contribute they will already have some of the knowledge they need. The printed view should have all the magic we've been using. I think this is in keeping with your suggestion above.

-- NoelWelsh - 20 Apr 2004

I mostly agree with that. The main reason I originally used a more book-like structure was because there didn't seem to be good options for supporting more than one view, and the book style seemed to be one of the major goals.

However, on an index page, providing links as plain WikiWords doesn't give you any kind of description of the linked topic. You can do it explicitly, with something like [[RavioliRecipe][Cooking Ravioli with Scheme]], but it's more work, and edits of topic descriptions have to be done in more than one place, so things can get out of sync. Using %TOC{"RavioliRecipe"}% at least gives you the topic description automatically.

With my suggestion above, an index page might defined using something like this:

%CookbookIndex%
RavioliRecipe
BurgerRecipes
   TofuBurgerRecipe
   VeggieBurgerRecipe
MudPieRecipe
%EndIndex%

...and this could be translated to a wiki-style page which gives the WikiName along with topic descriptions, or translated to something oriented towards a book version which omits the WikiName and includes numbering or whatever.

Let me know if you see a simpler acceptable solution, I'm not looking to overcomplicate things.

-- AntonVanStraaten - 20 Apr 2004

Your way sounds good, especially if it doesn't bork on currently undefined recipes like StringRecipes does.

-- NoelWelsh - 21 Apr 2004

For an initial version of this at least, an s-exp representation would be easy to deal with, e.g.:

(chapter "String Recipes"
  (section StringRecipesIntro)
  (section "Recipes"
    (recipe StringBasics)
    (recipe IsAString)
    ...)
  (section "Other recipes of interest"
    ...)
  (section StringRecipeReferences))

The idea is still that this shouldn't contain any direct content, just headings and references to other topics. It would be translated by a Scheme servlet into the necessary HTML (or Twiki format) output. This would be the single source from which could be generated either a pure table of contents view, a mixed view in which e.g. certain sections like the intro are directly included on the page, or a one-big-page view which shows all the content on the same page (useful for printing, skimming, etc.) These different views would be created by including the appropriate plugin-style command on the page on which one of these views should appear, so there might be two or three pages which reference the same index structure.

The above is only an example. It would mean that the format used to create indexes vs. author recipes would be different. We could make them closer if that's considered important, but for initial development, the s-exp format keeps things simple.

-- AntonVanStraaten - 23 Apr 2004

I like this idea. If we could also add "Make a Recipe" and "Make a Chapter" buttons in relevant places I think that would be a big step forward. As there is effectively no practically-oriented Scheme literature we need to cover information that in the Perl and Python world is covered in other publications and doesn't fit the problem/solution/discussion recipe model (e.g. HowToInstallPLTFile). This requires a fairly flexible system so we have to be careful we aren't too limiting in what our system can express.

-- NoelWelsh - 27 Apr 2004

As noted on the dev list, a NewRecipe topic has been added. I've also written a first version of a program which implements the TOC mechanism described above. The current source is at SchemeTOC. This is a work in progress, not yet deployed.

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