CSS formatting

[adamschwartz]

@daveliepmann After working on c15070c to close the loop on #90, I discovered the odd indentation/formatting used in this project. Surprisingly I guess I’d never actually looked at the CSS source. How would you feel about using standard indentation for tufte.css?

[daveliepmann]

I chose the formatting standard used in this project because I see no need to give space to open- or close-braces, and because I find the horizontal staggering to be a useful visual/mental crutch for differentiating selector blocks.

Since "standard" CSS indentation decreases readability for me, the only value-add I see for using it would be to increase code consistency with external projects. Part of the reason I don't find that tremendously convincing is that I don't spend much time with CSS in other projects, so I have no mental overhead involved in context-switching. Is the unfamiliarity disruptive for other people? Are there other benefits to "standard" indentation that I'm not seeing?

[yb66]

In my case, I converted a lot of this to SCSS for my own project, and it was painful having to reformat everything to the standard. I don't remember if that was just to get rid of warnings, or because it also caused errors. Things like nesting definitely require reformatting.

It also puts me off coming back for updates that would otherwise be more easily merged.

On an editor with softwrapping at 80 chars (which is fairly normal) the parts with the media queries become really messy.

Not that I'm wanting to moan! :) Everyone has their preferred ways for formatting, just letting you know my experience.

Regards,

[daveliepmann]

@yb66 SCSS conversion is a substantial reason that did not come to my mind.

[daveliepmann]

...but on further inspection, don't tools like http://csstoss.com/ do this rather painlessly? Or even just selecting all the open-braces, add a newline after, then select all the close-braces, add a newline before, then re-indent the file?

I do recognize the issue of soft-wrapping, as well.

[crmackay]

i think specifying a format and providing the specification for a given linter/formatter tool would be very helpful. I think supporting such a tool and then enforcing its use with every merged commit would actually make it easier for people to make contributions and pull requests. I don't think anyone wants to spend their time fiddling with indents and braces, when you could just run a command on the *.css file before committing and be done with it. I'm indifferent about which format is chosen, just that it can be satisfied by running a simple command line tool prior to committing changes.

One option is stylelint.io but there are others as well.

edit: grammar

[daveliepmann]

I mean, we've had the CSS Style Guide section in the README since back in the days when dinosaurs roamed the earth and commits were sent by ship across the Atlantic. My policy on enforcing that standard has been

1. hope that people conform
2. accept PRs regardless
3. manually coerce nonconformant code into conformity

This project is less than 300 lines. I respectfully don't see the need to introduce a command-line tool dependency in order to automate the process of taking 90 seconds to correct the six to eight braces most PRs have.

I have been admittedly slow addressing bugs and PRs, but that's not due to style issues, it's due to external time pressure and the complexity of testing changes across many devices and scenarios.

[adamschwartz]

My intended original point, which I’m sorry for not making more clear, is that one’s eye is forced to zig-zag around to read the code.

Let’s compare the current formatting to two other options A and B.

Current:

.table-caption { float:right;
                 clear:right;
                 margin-right: -60%;
                 width: 50%;
                 margin-top: 0;
                 margin-bottom: 0;
                 font-size: 1.0rem;
                 line-height: 1.6; }

.sidenote-number { counter-increment: sidenote-counter; }

.sidenote-number:after, .sidenote:before { content: counter(sidenote-counter) " ";
                                           font-family: et-book-roman-old-style;
                                           position: relative;
                                           vertical-align: baseline; }

.sidenote-number:after { content: counter(sidenote-counter);
                         font-size: 1rem;
                         top: -0.5rem;
                         left: 0.1rem; }

.sidenote:before { content: counter(sidenote-counter) " ";
                   top: -0.5rem; }

blockquote .sidenote, blockquote .marginnote { margin-right: -82%;
                                               min-width: 59%;
                                               text-align: left; }    

p, footer, table, div.table-wrapper-small, div.supertable-wrapper > p, div.booktabs-wrapper { width: 55%; }

Option A

.table-caption               { float:right;
                               clear:right;
                               margin-right: -60%;
                               width: 50%;
                               margin-top: 0;
                               margin-bottom: 0;
                               font-size: 1.0rem;
                               line-height: 1.6; }

.sidenote-number             { counter-increment: sidenote-counter; }

.sidenote-number::after,
.sidenote::before            { content: counter(sidenote-counter) " ";
                               font-family: et-book-roman-old-style;
                               position: relative;
                               vertical-align: baseline; }

.sidenote-number::after      { content: counter(sidenote-counter);
                               font-size: 1rem;
                               top: -0.5rem;
                               left: 0.1rem; }

.sidenote::before            { content: counter(sidenote-counter) " ";
                               top: -0.5rem; }

blockquote .sidenote,
blockquote .marginnote       { margin-right: -82%;
                               min-width: 59%;
                               text-align: left; }    

p,
footer,
table,
div.table-wrapper-small,
div.supertable-wrapper > p,
div.booktabs-wrapper         { width: 55%; }

Option B:

.table-caption {
  float: right;
  clear: right;
  margin-right: -60%;
  width: 50%;
  margin-top: 0;
  margin-bottom: 0;
  font-size: 1.0rem;
  line-height: 1.6;
}

.sidenote-number {
  counter-increment: sidenote-counter;
}

.sidenote-number::after,
.sidenote::before {
  content: counter(sidenote-counter) " ";
  font-family: et-book-roman-old-style;
  position: relative;
  vertical-align: baseline;
}

.sidenote-number::after {
  content: counter(sidenote-counter);
  font-size: 1rem;
  top: -0.5rem;
  left: 0.1rem;
}

.sidenote::before {
  content: counter(sidenote-counter) " ";
  top: -0.5rem;
}

blockquote .sidenote,
blockquote .marginnote {
  margin-right: -82%;
  min-width: 59%;
  text-align: left;
}

p,
footer,
table,
div.table-wrapper-small,
div.supertable-wrapper > p,
div.booktabs-wrapper {
  width: 55%;
}

Having written hundreds of thousands of lines of CSS in my life I’m most used to reading Option B, but I can absolutely see a case being made for something like Option A. That being said I have a hard time seeing how Option A doesn’t surpass the current formatting in readability. Of course, as you point out, it’s <300 lines so it’s no big deal either way.

[daveliepmann]

At this point I'm leaning towards something more conventional, so that it's more readable and in line with CSS norms in the broader community. Option B seems like it will be more recognizable for folks.

[yb66]

I'd go for option B too. Is there not a way to specify a format that is human readable and machine readable for several formatters/linters?

[daveliepmann]

I finally got around to this. Thanks for raising this issue Adam, and thanks to everyone else for adding your two cents.

Please, if you have a minute, take a look at the commit (bfbe3b5) and let me know if A) any indentation or statements could be further standardized, or B) you notice any implementation changes. (I have not implemented any way to test changes except manually scrolling through the sample doc.)

[yb66]

It looks good to me, @daveliepmann. I know how hard it can be to find the energy to face old issues like this so the effort is much appreciated! I'm in the process of re-publishing my blog to a new site so I'l use these changes and let you know if I find any problems.

[adamschwartz]

@daveliepmann looks great. Thank you so much for doing this.

[ghost]

@yb66 Do... do you have your SCSS around somewhere? Like, in github? I'm using an email tool that allows overriding the styling when displaying HTML mime parts, and it uses SCSS. I'd love to use Tufte for this, and if somebody's already done an SCSS conversion it'd make that a whole lot easier.

[adamschwartz]

@serussell Isn’t CSS valid SCSS?

[ghost]

@adamschwartz 🤷 It didn't occur to me; I'm not a web developer. But it appears that you're right: SCSS is a superset of CSS. Good news, everyone!

[CxRes]

May I suggest also suggest using a linter! Stylelint lights up like its Christmas when I use the css here. While some of those are an issue of style, there are many inconsistencies as well which we can get rid of easily.