Any manual on cell grouping management?

Question

Recently I come back to the problem of cell grouping and performed extensive search on this site and on MathGroup archive for information on how to use the possible values of the CellGroupingRules option. I have found surprisingly little: there are only two rather old MathGroup posts (both I link and cite in this answer) and almost nothing more.

The first is 2000 year post by P.J. Hinton (Wolfram Research) which seems to be outdated in many respects. For example, it states that

"InputGrouping", "OutputGrouping", and "GraphicsGrouping" don't group with any cells that appear after them.

But currently it isn't true: "InputGrouping" groups both with "OutputGrouping" and "GraphicsGrouping" appearing after it, and "GraphicsGrouping" groups with itself. This can be proven as follows:

rulesList = {"InputGrouping", "OutputGrouping", "GraphicsGrouping", 
   "GraphicsGrouping", "GraphicsGrouping", "OutputGrouping", "OutputGrouping"};
Do[CellPrint[
  Cell[ToString[rule, InputForm], CellGroupingRules -> rule, FontSize -> 16, 
   FontFamily -> "Courier", CellFrame -> True, 
   CellBracketOptions -> {"Thickness" -> 5, "Widths" -> {50, 18}, 
     "Color" -> Red}]], {rule, rulesList}]

Also cited post states (emphasis is mine):

Grouping rule names that use strings only include "InputGrouping", "OutputGrouping", and "GraphicsGrouping".

But with Mathematica 10.4.1 I get a suggestion to use the form {"InputGrouping", 30}:

This form is accepted without warnings for the all grouping rule names listed in the last citation. I wasn't able to figure out how it affects cell grouping: looks like the integer argument is simply ignored. But if the latter is true, why is this form suggested at all?!

Also that post provides no information about new in version 6 "GroupTogetherGrouping" and "GroupTogetherNestedGrouping".

The second is 2007 year post by Derek who summarized own findings on the subject. Unfortunately this post is written in a rather clumsy way, contains a couple of wrong conjectures and essentially adds nothing to the old 2000 year post by P.J. Hinton.

On this site I found this answer by Kyle Keane (Wolfram Research) who briefly mentions that "GroupTogetherNestedGrouping" is intended

... to stay in the same grouping space as list stuff normally resides (look into the Default stylesheet at "Styles for Body Text > Display > Lists > Bulleted").

Unfortunately this is all what he said and no examples demonstrating how it can be used are given.

The question

Is there any manual on the use of the CellGroupingRules option? If not, could anyone summarize own experience of working with this option and give some enlightening examples of use?

---

Addendum: usage statistics

I grepped all the *.nb, *.cdf and *.m files in the Mathematica 10.4.1 installation folder using PowerGrep with regular expression CellGroupingRules\s?->\s?(".+?"|{.+?}) (total 24776 matches in 10398 files) and collected the following statistics:

• For the {"SectionGrouping", _Integer} form the second argument may be negative, for example the form {"SectionGrouping", -5} is found 28 times.
• The form {"SectionGrouping", Inherited} is found 100 times and the form {"TitleGrouping", Inherited} is found 60 times. They are found only inside of Palettes.
• "GroupTogetherGrouping" is more often used without quotes as GroupTogetherGrouping (120 times vs 1215 times correspondingly).
• "GroupTogetherGrouping" and "GroupTogetherNestedGrouping" are never used directly, they always present inside of the {type, n} form with n being a number.
• The form {"GraphicsGrouping", 0} is used in the "PublicationDefault.nb" stylesheet for the style "SingleLine" and also in the "Monograph.nb" stylesheet for the style "FigureCaptionLabel" and in some other places (total 21 times). The forms {"InputGrouping", 20100} and {"OutputGrouping", 20100} are used only in the file ".\SystemFiles\Components\MUnit\FrontEnd\StyleSheets\MUnit\MUnit.nb". The types "InputGrouping", "OutputGrouping" and "GraphicsGrouping" are used directly in the all other places.
• There are 70 cases of {$CellContext`GroupTogetherGrouping, 10000.} and 21 cases of {FrontEnd`Private`GroupTogetherGrouping, 999.}.

Just for the fun I also grepped the installation folder of Mathematica 5.2 and found that the form {GroupTogetherGrouping, 10000.} is used in the "Reference.nb" stylesheet, and the type "GroupTogetherNestedGrouping" is used many times in different files. So these types actually aren't new in version 6: they just aren't listed in the Options Inspector of version 5.2.

Answer 1

You've got a voluminous question, so maybe this is contained in it (I did check, but I'm also dumb), but here's what I've found:

"TitleGrouping"

"TitleGrouping" is distinct from "SectionGrouping" as subgroups are not formed.

{"TitleGrouping", n} groups the following:

• {"TitleGrouping", m} such that m > n
• {"SectionGrouping", m} such that m > n
• {"GroupTogetherGrouping", m} such that m > n
• "InputGrouping" / {"InputGrouping", n}
• "OutputGrouping" / {"OutputGrouping", n}
• "NormalGrouping" / {"NormalGrouping", n}
• "GraphicsGrouping" / {"GraphicsGrouping", n}

"SectionGrouping"

Base grouping everyone knows, {"SectionGrouping", n} groups the following:

• {"TitleGrouping", m} such that m > n
• {"SectionGrouping", m} such that m > n
• {"GroupTogetherGrouping", m} such that m > n
• "InputGrouping" / {"InputGrouping", n}
• "OutputGrouping" / {"OutputGrouping", n}
• "NormalGrouping" / {"NormalGrouping", n}
• "GraphicsGrouping" / {"GraphicsGrouping", n}

"NormalGrouping"

No grouping, as far as I can tell

"GroupTogetherGrouping"

{"GroupTogetherGrouping", n} groups the following:

• {"GroupTogetherGrouping", n}

"GroupTogetherNestedGrouping"

{"GroupTogetherNestedGrouping", n} groups the following:

• {"GroupTogetherNestedGrouping", m} such that m >= n
• {"GroupTogetherGrouping", m} such that m > n

"InputGrouping"

{"InputGrouping", n} == "InputGrouping" groups the following:

• "OutputGrouping" / {"OutputGrouping", n}
• "GraphicsGrouping" / {"GraphicsGrouping", n}

"OutputGrouping"

{"OutputGrouping", n} == "OutputGrouping" groups nothing as far as I can tell

"GraphicsGrouping"

{"GraphicsGrouping", n} groups the following:

• {"GraphicsGrouping", m} such that m >=n

Notes:

I've never found myself having to use anything other than "Section" and the "GroupTogether*" styles. I commonly use {"GroupTogetherGrouping", 0} on things like delimiters that should break up all cell grouping. Of course they group with each other, but generally I use "OverlapContent"->True anyway.