recipes

About the Recipes

The generated CSS is stored in the ./output directory.

Relevant Scripts

./script/fetch-html ${book_name}     # Stores result in `./data/`
./script/bake-book ${book_name}      # Uses the results of `./script/fetch-html`
./script/build-guide ${book_name}

Guide Documentation

The source for the documentation is in CSS comments and is split into common and book-specific.

An example config file with documentation

Directory Organizational Map

• ./recipes/mixins/styleguide/*.snippet.xml : The Raw HTML snippets for "common" elements in a Page
• ./recipes/mixins/styleguide/_all.scss: The documentation for "common" elements in a Page
• ./recipes/books/${book_name}/styleguide/*.snippet.xml : The Raw HTML snippets for book-specific collated pages and any other customizations
• ./recipes/books/${book_name}/book.scss: Added CSS docs that are slurped in when generating the styleguide

Book-Agnostic Documentation

The common documentation is in ./recipes/mixins/styleguide/_all.scss only because phil didn't know of a better place to put them but wanted them "near" the common code. That directory also contains the Raw HTML snippets.

Book-Specific Documentation

The book-specific documentation is done as comments in the ./recipes/books/${book_name}/book.scss and ./recipes/books/${book_name}/_config.scss files and the Raw HTML snippets are in ./books/${book_name}/styleguide/.

Variable Naming Conventions

There are 4 different types of variables used in the SASS files:

• starts with Config_: these are defined in the config file and are the only ones used as input to _generator.scss
• $UPPER_CASE: these are enums (SASS does not have native enums) and are used when you must select 1 of several options.
  • Example: $AREA_NONE, $AREA_EOC, $AREA_EOB
• $_privateVar: these are declared and used within the SCSS file
• $PascalCase: these are defined in one _config.scss file but are used in another _config.scss file

Config Settings Hierarchy

The config settings are variables that start with $Config_ and have the following structure:

• $Config_ChapterCompositePages: A list of Pages
• $Config_BookCompositePages: A list of Pages
• $Config_SetTableCaption: A Caption
• $Config_SetFigureCaption: A Caption
• $Config_TargetLabels: A list of TargetLabels
• $Config_Notes: A list of Notes
• $Config_UnnumberedElements: A list of UnnumberedElements
• $Config_PartType_*
  • $Config_PartType_Exercise: A CustomPart
  • $Config_PartType_Example: A CustomPart
  • $Config_PartType_Chapter: A CustomPart
  • $Config_PartType_Equation: A CustomPart
  • $Config_PartType_Solution: A CustomPart
  • $Config_PartType_Chapter_TitleContent: A TitleContent
  • $Config_PartType_Unit_TitleContent: A TitleContent
  • $Config_PartType_Appendix_TitleContent: A TitleContent
  • $Config_PartType_Section_TitleContent: A TitleContent
  • $Config_PartType_Table_CaptionContent: A TitleContent
  • $Config_PartType_Table_CaptionContentAp: A TitleContent
  • $Config_PartType_Figure_CaptionContent: A TitleContent
  • $Config_PartType_Figure_CaptionContentAp: A TitleContent
  • $Config_Index_SymbolRegexp: A regular expression (in a string)
  • $Config_Index_NotSymbolRegexp: A regular expression (in a string)
• $Config_Coverage_*
  • $Config_Coverage_MayHaveSimlinks: a boolean
  • $Config_Coverage_MayHaveIframes: a boolean
  • $Config_Coverage_MayHaveMissingExercises: a boolean
• $Config_HACK_modifyAnyContainerTitleSelector: a boolean
• $Config_hasCompositeAppendixes: a boolean (used for some TEA books)
• $Config_hasCitation: a boolean used for References.

TitleContent

This is a map whose keys are the className of the element that will be created (ie os-divider or os-number) and the values are the css that will be used (ie "|" or counter(exercise)).

Example:

(
  os-title-label: "Example",
  os-divider: " ",
  os-number: counter(chapter) "." counter(example),
  os-divider: ":",
)

Page

These are the end-of-chapter/book pages that are autogenerated.

A Page contains the following fields:

• className: the class name (and bucket) of the page
• name: The title of the new page (TODO rename?)
• hasSolutions: true when this item contains exercises that contain solutions
  • (TODO: why is this necessary?)
• clusterBy: $CLUSTER_SECTION, $CLUSTER_CHAPTER, or $CLUSTER_NONE when items on this page should be organized by Section/Chapter
  • A header is added which contains the section number and title
• specialPageType: (optional) There are also a couple of "special" pages: $PAGE_INDEX and $PAGE_GLOSSARY which contain additional configuration fields.
• childPages: (optional) Some generated pages are just a container for other Pages. This contains the list of child Pages that need to be generated

Also, a set of styleguide comments occur above for each composite page. Having it here makes it easy to remember to update the documentation and by having it above the $Config_ChapterCompositePages helps make this area more readable (since it sort of looks like a table).

Caption

This configures a Table or Figure caption.

A Caption contains the following fields:

• captionType: whether this is for a table or a figure
  • $CAPTION_TABLE
  • $CAPTION_FIGURE
• defaultContainer: An element that is created to contain the caption
• hasCaption: a boolean
• hasTitle: a boolean

TargetLabel

Configure the labels of links. You will likely just extend the default set with a label for items specific to this book, like links to Try It notes.

(TODO: maybe this should be the default for links to Notes?) NOTE: These selectors MUST match the counting selectors or be more specific otherwise, the increment and the counter() call may fire in the wrong order.

A TargetLabel contains the following fields:

• selector: This a selector that matches the target of a link
• labelText: This is the text that will be inside the link
  • It can be a list or a map. If it is a map (used in i18n), the key corresponds to the @cmlnle:case="..." attribute. see #353

Note

These are a Set of "Feature boxes" that are specific to the book.

A Note contains the following fields:

• className: the class name of the Note
• moveSolutionTo: Where the solution can be moved to.
  • $AREA_NONE keeps the solution in place
  • $AREA_TRASH discards the solution
  • $AREA_EOC moves the solutions to the end of a chapter
  • $AREA_EOB moves the solutions to the end of the book
• labelText: A simple string for the title. cannot be used with titleContent
• titleContent: what the autogenerated title should look like.
  • Most notes are just a string but some, like "Try It" are prefaced with which section they occur in
• counterName: (optional) used in conjunction with titleContent to specify the name of the counter

UnnumberedExercise

Sometimes exercises (or equations) in notes should not be numbered. This shows which ones.

The name of this type is currently a little confusing but it is this because the need for unnumbered Exercises came before the need for unnumbered Equations.

TODO: It would be nice to move these into the note config but it seems like the context is not always a note, and the child is not always an exercise/equation. so the proper place to put this requires a bit more thought

It contains the following fields:

• contextSelector
• childSelector: (optional)

CustomPart

This contains additional elements in the book (like an equation, exercises, solutions) Each entry has a few common fields that can be set:

• moveTo: specifies where to move this element to

  • $AREA_TRASH_HALF (only for Config_PartType_Solution) will mark half of solutions for deletion before collation to the answer key

• resetAt: specifies when the counters should reset

  • $RESET_SECTION resets for each module
  • $RESET_CHAPTER resets for each chapter
  • $RESET_COMPOSITE_PAGE resets for each autogenerated page

• titleContent: The generated title for this element

• outlineTitle: (optional) Only used by Chapter

• numberAt: (optional) Only used by Exercise

• solutionTitleContent: (optional) Only used by Example

• excludeNumberingInClassName: (optional) Only used by Equation

• hasLearningObjectives: (optional) Only used by Chapter Outline