StyleSheets from scratch: Documentation on CellGroupingRules?

Questions
, ,
1

The documentation on CellGroupingRules has a warning that it is not fully integrated. However, because it is used in the standard supplied StyleSheets, I am guessing that it may be around for a while.

In any case, the documentation for CellGroupingRules is sparse. Can anyone point me to something with a little more detail?
I am trying to back out what CellGroupingRules should do by looking at various style sheets---but I am hopeful that someone might have a pointer.

In my case, I’m building a private style sheet from scratch. I’m not using the Default styles, so my private style sheet starts like this:

StyleData[StyleDefinitions -> "Default.nb"]
StyleData[StyleDefinitions -> "StyleMenuClear.nb"]

I’d like to control automatic grouping. As a familiar example, here might be a set of Styles for a private stylesheet for a book. (This is not what I am doing, but hopefully serves to illustrate)

I’ve tried doing this by using manual grouping in the style sheet editor, this doesn’t seem to work.

Style Book always starts a new cell group
Style Chapter is subgrouped with its particular Book
Style Section is subgrouped with its particular Chapter

Any FigureTitle is subgrouped to whatever is immediately above (*having the effect of closing the figures and captions and retaining the title*)
Any Figure is subgrouped to a FigureTitle
Any FigureCaption is subgrouped to a Figure

Any Text is subgrouped to whatever is immediately above.

Any ReferencesList is subgrouped to a Chapter, but is not subgrouped to Section

Any IndexList is subgrouped to a Book, but nothing else.

2

I think all of these can be handled using the “SectionGrouping” type, which is what all of the documentation style sheets use for cell grouping.

From http://reference.wolfram.com/mathematica/ref/CellGroupingRules.html:

CellGroupingRules can also be set to {type,n}, where type is selected from a list and n is an integer that gives the precedence of the grouping relative to other cells of the same type.

You said you’ve seen CellGroupingRules in style sheets already, so you’ve very likely seen this construction already. “type” can be “SectionGrouping”, and n can be arbitrary and will change based on the style you’re dealing with (lower numbers have stronger grouping, and two cells with the same value will not group under each other). So, something like:

Cell[StyleData["Book"], CellGroupingRules->{"SectionGrouping", 10}]
Cell[StyleData["Chapter"], CellGroupingRules->{"SectionGrouping", 20}]
Cell[StyleData["Section"], CellGroupingRules->{"SectionGrouping", 30}]
Cell[StyleData["FigureTitle"], CellGroupingRules->{"SectionGrouping", 40}]
Cell[StyleData["Figure"], CellGroupingRules->{"SectionGrouping", 50}]
Cell[StyleData["FigureCaption"], CellGroupingRules->{"SectionGrouping", 60}]
Cell[StyleData["Text"]]
Cell[StyleData["ReferencesList"], CellGroupingRules->{"SectionGrouping", 30}]
Cell[StyleData["IndexList"], CellGroupingRules->{"SectionGrouping", 15}]

If you want “Text” to group under anything else like you specified, including FigureCaption, then you don’t have to provide CellGroupingRules; it will group under anything that does have CellGroupingRules. If you want it to group equally to a particular other style, then give it the equivalent CellGroupingRules.

Hope this helps,
-Brian

3

Thanks Brian,
This is useful.

That url seems to be broken; so I can’t tell if it is different than the documentation page for CellGroupingRules---I don’t think so though.

I’ve been noodling around a bit, I’ve found 8 different “types”:

GraphicsGrouping
GroupTogetherGrouping
GroupTogetherNestedGrouping
InputGrouping
NormalGrouping
OutputGrouping
SectionGrouping
TitleGrouping

I’m not sure where those types and their behavior are defined. Future readers of this might find the descriptions useful?

Sometimes these types are called in different ways; these are from the supplied style sheets in version 9 (note: sometimes as a String, other instances not):

Wolfram/Reference.nb: CellGroupingRules->{GroupTogetherGrouping, 10000.}],
Report/ConfidentialReport.nb: CellGroupingRules->“GraphicsGrouping”
Creative/NaturalColor.nb: CellGroupingRules->{“GroupTogetherNestedGrouping”, 15050}],

4

The URL works and is hyperlinked now. But I think it is the same reference article you mentioned in your original question. I think Brian just quoted info from “Details” section of that article.

5

Strongly related Mathematica.SE thread: