<commit_before># About the Rulesets

The generated CSS is stored in the [./output](./output) directory.

## Relevant Scripts

```sh
./scripts/bake-book ${bookName}  # Uses the results of `./scripts/fetch-html` stored in `/data`
./scripts/generate-guide ${bookName}
```


# Guide Documentation

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

## Directory Organizational Map

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

## Book-Agnostic Documentation

The common documentation is in `./rulesets/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 `./rulesets/books/${bookName}/book.scss` and `./rulesets/books/${bookName}/_config.scss` files and the Raw HTML snippets are in `./books/${bookName}/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_ChapterTitleContent`: A [TitleContent](#titlecontent)
- `$Config_AppendixTitleContent`: A [TitleContent](#titlecontent)
- `$Config_SectionTitleContent`: A [TitleContent](#titlecontent)
- `$Config_CaptionTableNumber`: A [TitleContent](#titlecontent)
- `$Config_CaptionTableNumberAp`: A [TitleContent](#titlecontent)
- `$Config_CaptionFigNumber`: A [TitleContent](#titlecontent)
- `$Config_CaptionFigNumberAp`: A [TitleContent](#titlecontent)
- `$Config_ChapterCompositePages`: A list of [Pages](#page)
- `$Config_BookCompositePages`: A list of [Pages](#page)
- `$Config_SetTableCaption`
- `$Config_SetFigureCaption`
- `$Config_TargetLabels`: A list of [TargetLabels](#targetlabel)
- `$Config_Notes`: A list of [Notes](#note)
- `$Config_UnnumberedExercises`: A list of [UnnumberedExercises](#unnumberedexercise)
- `$Config_PartType_*`
  - `$Config_PartType_Exercise`: A [CustomPart](#custompart)
  - `$Config_PartType_Example`: A [CustomPart](#custompart)
  - `$Config_PartType_Chapter`: A [CustomPart](#custompart)
  - `$Config_PartType_Equation`: A [CustomPart](#custompart)
  - `$Config_PartType_Solution`: A [CustomPart](#custompart)
- `$Config_Coverage_*`
  - `$Config_Coverage_MayHaveSimlinks`: a boolean
  - `$Config_Coverage_MayHaveIframes`: a boolean
  - `$Config_Coverage_MayHaveMissingExercises`: a boolean
- `$Config_HACK_modifyAnyContainerTitleSelector`: a boolean


## 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:

```scss
(
  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?)
- `sectionSeparated`: `true` when items on this page should be organized by Section
  - A header is added which contains the section number and title
- `chapterSeparated`: `true` when items on this page should be organized by Chapter (only for end-of-book Pages)
  - 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).


## 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


## Note

These are a Set of "Feature boxes" that are specific to the book.<commit_msg>:art: document caption configuration<commit_after># About the Rulesets

The generated CSS is stored in the [./output](./output) directory.

## Relevant Scripts

```sh
./scripts/bake-book ${bookName}  # Uses the results of `./scripts/fetch-html` stored in `/data`
./scripts/generate-guide ${bookName}
```


# Guide Documentation

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

## Directory Organizational Map

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

## Book-Agnostic Documentation

The common documentation is in `./rulesets/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 `./rulesets/books/${bookName}/book.scss` and `./rulesets/books/${bookName}/_config.scss` files and the Raw HTML snippets are in `./books/${bookName}/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_ChapterTitleContent`: A [TitleContent](#titlecontent)
- `$Config_AppendixTitleContent`: A [TitleContent](#titlecontent)
- `$Config_SectionTitleContent`: A [TitleContent](#titlecontent)
- `$Config_CaptionTableNumber`: A [TitleContent](#titlecontent)
- `$Config_CaptionTableNumberAp`: A [TitleContent](#titlecontent)
- `$Config_CaptionFigNumber`: A [TitleContent](#titlecontent)
- `$Config_CaptionFigNumberAp`: A [TitleContent](#titlecontent)
- `$Config_ChapterCompositePages`: A list of [Pages](#page)
- `$Config_BookCompositePages`: A list of [Pages](#page)
- `$Config_SetTableCaption`: A [Caption](#caption)
- `$Config_SetFigureCaption`: A [Caption](#caption)
- `$Config_TargetLabels`: A list of [TargetLabels](#targetlabel)
- `$Config_Notes`: A list of [Notes](#note)
- `$Config_UnnumberedExercises`: A list of [UnnumberedExercises](#unnumberedexercise)
- `$Config_PartType_*`
  - `$Config_PartType_Exercise`: A [CustomPart](#custompart)
  - `$Config_PartType_Example`: A [CustomPart](#custompart)
  - `$Config_PartType_Chapter`: A [CustomPart](#custompart)
  - `$Config_PartType_Equation`: A [CustomPart](#custompart)
  - `$Config_PartType_Solution`: A [CustomPart](#custompart)
- `$Config_Coverage_*`
  - `$Config_Coverage_MayHaveSimlinks`: a boolean
  - `$Config_Coverage_MayHaveIframes`: a boolean
  - `$Config_Coverage_MayHaveMissingExercises`: a boolean
- `$Config_HACK_modifyAnyContainerTitleSelector`: a boolean


## 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:

```scss
(
  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?)
- `sectionSeparated`: `true` when items on this page should be organized by Section
  - A header is added which contains the section number and title
- `chapterSeparated`: `true` when items on this page should be organized by Chapter (only for end-of-book Pages)
  - 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


## Note

These are a Set of "Feature boxes" that are specific to the book.
{'fraction_non_alphanumeric': 0.10572538422563756, 'fraction_numerical': 0.00033778078027360244, 'mean_word_length': 4.981313131313131, 'pattern_counts': {'":': 2, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4182367', 'n_tokens_mistral': 3633, 'n_tokens_neox': 3407, 'n_words': 1380}