Multiple global style improvements #1079

tkoeppe · 2016-11-20T17:16:34Z

Bulleted lists spaced uniformly consistently with paragraphs.
Bulleted lists work regardless of newlines in the source.
All indents are now the same (1em): grammar, codeblocks, itemdecls.
Grammar spaced uniformly consistently with paragraphs. (Removed use of minipages.)
Removed unnecessary simplebnf environment. "Simple" grammar now uses less space and generally flows better with its surrounding paragraph.
Removed excessive whitespace at the end of examples.

burblebee · 2016-11-22T00:37:52Z

source/preprocessor.tex

 \indextext{\idxcode{\#elif}}%
-\terminal{\# elif}\>\>constant-expression new-line group\opt


What does > do, and does it only have special meaning in grammars?

This is a tab stop in a tabular setting. But I figured that that was completely unnecessary here (and I have also changed the tab stops to fit better with the main grammars, so this wasn't quite working anymore.)

burblebee · 2016-11-22T00:39:01Z

source/macros.tex

@@ -424,32 +424,30 @@
 \newcommand{\nonterminal}[1]{{\BnfNontermshape #1}}

 \newenvironment{bnfbase}
- {
+ {%


Does % do anything here?

No, it was just left over from an earlier experiment. This block is already introducing whitespace, so this doesn't make a difference.

… indent. Each item is now separated from other items and from ambient paragraphs by the same amount as paragraphs are separated from one another. This is also true for paragraphs within an item, and for nested lists. This was achieved by modifying the 'itemize' and 'enumerate' environments to set the relevant lengths appropriately, and by resetting the depth counter to 0 for every list, regardless of actual nesting level, to overcome hardcoded scaling logic in the fundamental 'list' environment. Lists are now spaced independently of whether they are preceded by a paragraph break (because partopsep is now zero). Also changes the 'itemdecl' environment to not use lists for indentation, but 'adjustwidth' instead, and decreased the indentation to the same as for code listings.

… minipages

zygoloid · 2016-11-22T02:09:37Z

I'm currently looking through the standard with this applied. Mostly it looks really good. A raw stream of consciousness of some thoughts:

Lists look a little cramped right now, but I'm not sure if that's just overfamiliarity with the old style leading me astray.
[lex.charset]/1's table of characters looks a little silly now the extra whitespace above and below the character set list is gone -- there's significantly more space between rows than above and below the table.
Grammar snippets are not indented enough for my tastes, both text -> grammar and non-terminal -> alternatives indents aren't enough to clearly separate them from the surroundings. Can we retain bullet indent for these? (That said, the indent of [lex.pptoken]/3.1's snippet looks nice as-is.)
[lex.pptoken]/3's example still has imbalanced vertical whitespace, but I'm not sure if that's a source problem for this particular example or something more general.
Removal of minipages is permitting grammar productions to be split across pages, which we previously were trying hard to avoid (that's why we had them), eg pp-number production in 2.9. The problem of productions split across page boundaries is worsened by the reduced grammar indent.
We have a lot of vert whitespace around tables, and it's a little jarring now there's not much anywhere else.
Footnote 23 has been laid out on top of the bottom margin / section number.
Going back to point 1, I think there is some value in inter-paragraph and inter-list-item spacing being different. It's less obvious where the paragraph boundaries are with the new spacing (even though the paragraph spaces used to be /less/ than the list-item spacing). I wonder whether adding a little extra vertical space with each \pnum would help.
Page 90 has some text flowing slightly into the footnote area.
5.2.11/7 has a lot of vertical whitespace (block math mode). Something about that extra whitespace comes as a relief after 100 pages of dense text with little vertical rest :)
5.20/2.10 (nested list bullets) have bad vertical whitespace
[skipping clause 7-12]
inline grammar snippets still looking really nice with the codeblock indent (13.3.1.1.2 has some good examples)
13.3.1.8/1.2 again has bad vspace with nested lists, and before 13.3.3.2/3.3
13.5/1: operator-function-id: definition is slightly more indented than operator: definition
13.5.6 has inconsistent indentation for the two lines of grammar snippet
[skipping to clause 20]
20.2.6: where did the paragraph number and lack of indent here come from?
I think I'm generally ok with less itemdescr indentation, but when the itemdecl ends with an indented continuation line, there is now sometimes no difference in indentation between the declaration "heading" and the pieces below it. I wonder if we can do better there. Crazy idea: move itemdecls left a bit (into the left margin)
20.5.2.1/17: something bad happened to the list here, and in 20.5.2.6/6, and throughout 20.7.2.3
There's more vertical space above itemdecls than other vertical whitespace elsewhere. I like that distinction; these act more like "little headings".
20.5.2.7/7: someone sure felt excited that that case was not valid

tkoeppe · 2016-11-22T02:22:30Z

Thanks a lot for the review! I'm going to close this and start extracting smaller parts, keeping the things we like and discarding the ones we don't.

jwakely · 2016-11-22T14:16:16Z

IMHO...

The reduced whitespace after codeblocks is nice.

While the denser itemize envs are certainly more consistent with paragraph spacing I don't always find them easier to read. In complex cases like [dcl.init] I think it is an improvement, so overall I like it.

Making the grammar use the same indentation as codeblocks looks nice, although I'm less keen on the second level for indentation for the grammar expressions also reducing. Not a big deal though.

Postscript: the more I look at the denser itemize lists the more I like them, so maybe it was over-familiarity in my case too.

tkoeppe · 2016-11-22T14:19:56Z

@jwakely: Thanks! I will be sending individual PRs to implement each of the things we like.

tkoeppe force-pushed the style branch 2 times, most recently from 8d3f158 to decc869 Compare November 20, 2016 21:26

burblebee reviewed Nov 22, 2016

View reviewed changes

[macros] Space codeblocks more evenly; less trailing whitespace.

5a0de1d

tkoeppe force-pushed the style branch from decc869 to ebb2bb0 Compare November 22, 2016 01:01

tkoeppe added 6 commits November 22, 2016 02:02

[macros] Improve vertical consistency of BNF environments by removing…

c37fd68

… minipages

[lex] Minor spacing and flowing tweaks

36d9b7f

Replace 'simplebnf' with 'bnf' environment

e0c03ea

[macros] Remove unused 'simplebnf' environment

4f179cc

[cpp] Improve presentation of intra-paragraph grammar

18edb85

tkoeppe force-pushed the style branch from ebb2bb0 to 18edb85 Compare November 22, 2016 02:02

tkoeppe closed this Nov 22, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Multiple global style improvements #1079

Multiple global style improvements #1079

tkoeppe commented Nov 20, 2016

burblebee Nov 22, 2016

tkoeppe Nov 22, 2016

burblebee Nov 22, 2016

tkoeppe Nov 22, 2016

zygoloid commented Nov 22, 2016

tkoeppe commented Nov 22, 2016

jwakely commented Nov 22, 2016 •

edited

tkoeppe commented Nov 22, 2016

		\indextext{\idxcode{\#elif}}%
		\terminal{\# elif}\>\>constant-expression new-line group\opt

Multiple global style improvements #1079

Multiple global style improvements #1079

Conversation

tkoeppe commented Nov 20, 2016

burblebee Nov 22, 2016

Choose a reason for hiding this comment

tkoeppe Nov 22, 2016

Choose a reason for hiding this comment

burblebee Nov 22, 2016

Choose a reason for hiding this comment

tkoeppe Nov 22, 2016

Choose a reason for hiding this comment

zygoloid commented Nov 22, 2016

tkoeppe commented Nov 22, 2016

jwakely commented Nov 22, 2016 • edited

tkoeppe commented Nov 22, 2016

jwakely commented Nov 22, 2016 •

edited