Re: Column examples

Hi everyone,

Sorry for this long email but I wanted to describe my process and some
tough encounters. I also would love your feedback to see if this makes
sense. I know the columns property is just one of many however this process
will really set a precedence (at least for me) in terms of how I approach
this and view all the docs that are out there on the web today. I
originally only contributed the examples portion of this columns article
but I've gone ahead and updated the summary, values/syntax sections since I
found it strange that the existing examples are only related to width (auto
and length) per David's notes and additionally there were two syntax
sections leading to additional confusion. I've broken this up to address
three problem areas:

*Problem 1 - Example inconsistencies (resolved!)*

David - I agree, there were some strange inconsistencies! Thanks for
pointing those out. I grabbed some of these example variations from the W3C
doc (http://www.w3.org/TR/css3-multicol/#columns0) however in most browser
implementations, the order *does* matter so it's important to have people
follow the consistency of column-width || column-count if they are setting
both with one as auto. I've also updated example variations in the gist to
follow the shorthand guidelines as I've noted and made them display 3
columns for consistency across the full example.

http://code.webplatform.org/gist/6288803
http://docs.webplatform.org/wiki/css/properties/columns

*Problem 2 - Summary inconsistencies (please review)*

Our summary currently states "This property describes the width of columns
in multicolumn elements."

Which only talks about the width property (which explains why original
values only spoke to the column-width as they were auto and length). We'll
address this later in problem 3 below...

Upon reviewing...
https://developer.mozilla.org/en-US/docs/Web/CSS/columns
http://www.opera.com/docs/specs/presto28/css/multicolumnlayout/
http://msdn.microsoft.com/en-us/library/ie/hh771860(v=vs.85).aspx
http://www.w3.org/TR/css3-multicol/#columns0

I continued to review the summary of the other docs and additionally found
the content a little bit misleading (especially MDN's)...

   - MDN describes "The columns CSS property is a shorthand property
   allowing to set both the column-width and the column-count properties at
   the same time."
   - MSDN describes "Gets or sets a shorthand value that specifies values
   for the column-width and the column-count of a multi-column element."
   - Opera describes "This property is a shorthand property for setting
   column-width and column-count. Omitted values are set to their initial
   values."
   - W3C describes "This is a shorthand property for setting ‘column-width’
   and ‘column-count’. Omitted values are set to their initial values."

If you attempt to set both, it doesn't actually always work which was the
original Opera problem that kicked off this conversation... and the fact
that if you set both, the width is never actually determined following the
auto-fill to column count description.

My new proposed summary: *"This property is a shorthand property for
setting column-width or column-count. Omitted values are set to their
initial value of auto."*

Please review and let me know if you have a revision.

*Problem 3 - Values and Syntax formatting for shorthand properties (please
review)*

With the current wiki format, values and syntax come from the editing
inputs. Setting column-width and column-length was an important update for
values (instead of auto and length) however after updating that, it doesn't
give me the proper formal syntax where order is important as they become
bulleted.

This is a similar issue I'm seeing in background, border and other
shorthand properties:
http://docs.webplatform.org/wiki/css/properties/background (bulletted)
http://docs.webplatform.org/wiki/css/properties/border (inline but value
definitions had to all be in one input)

The current quick fix is to add a *Formal syntax* section (I've updated
from Syntax to Formal syntax to reduce duplication) in important notes
which I've done but this could lead to confusion for other viewers who see
two syntax sections. MDN and MSDN only have one nice area for syntax.

Let me know what your thoughts are on this and if this should be filed for
improvement?

Additionally, for shorthand properties, should we just link them to the
description of those CSS property values like MSDN does or explain on the
page what they are on the page like MDN's? I've linked them off to their
respective properties for now. I think this will be a good thing to
determine for consistency throughout our docs.

-----

I think the columns section is in much better shape pending summary
approval and how we want to go about formatting values. I apologize for the
confusion on all this but glad we're working through it as this makes me
realize how important this initiative is considering the docs out on the
web aren't always perfect. Thanks everyone!

-Shali




On Sun, Aug 25, 2013 at 12:55 AM, David R. Herz <WPD@theherzes.com> wrote:
>
> Your Example variations make no sense, to me at least.
>
>
>
> On the explanation page,
http://docs.webplatform.org/wiki/css/properties/columns, we have:
>
>
>
> Syntax
>
> columns: Auto
>
> columns: Length
>
>
>
> Coming back to the Examples, http://code.webplatform.org/gist/6288803, we
see that
>
>
>
> Shorthand usage should follow: columns: 'column-width' || 'column-count'
>
>
>
> If that’s the case, these examples don’t make sense, or the explanation
is not clear:
>
>
>
> columns: auto 12em;    would fail because 12em isn’t a count, it is a
width
>
> columns: 2;   would only work if the browser reads the 2 as a column
count, which I don’t know is the automatic thing for it to do since column
looks for auto or length on its own and no length is here specified.
>
> columns: 2 auto;  doesn’t have a measurement for the width, which is
presumably the first element in the syntax.
>
>
>
> I am not an expert, rather an occasional reviewer, but my guess is you
indicated the syntax backwards, in which case it might be worth mentioning
that if just a length is provided, browsers parse the missing column count
as auto.  And just for consistency, I would make the example variations
also have a three column output, or indicate where they would vary from
that.
>
>
>
> David R. Herz
>
> wpd@theherzes.com
>
>
>
> From: Shali Nguyen [mailto:shalinguyen@gmail.com]
> Sent: Saturday, August 24, 2013 12:19 AM
> To: wpd@theherzes.com
> Cc: Scott Rowe; WebPlatform Public List
> Subject: Re: Column examples
>
>
>
> D'oh... thanks for catching. The example I had tried to be too specific.
It looks like shorthand for columns is "<'column-width'> ||
<'column-count'>" vs attempting to set both. I've updated the example and
documentation to explain as well.
>
>
>
> [1] Updated example: http://code.webplatform.org/gist/6288803
>
> [2] Updated example section in documentation:
http://docs.webplatform.org/wiki/css/properties/columns
>
>
>
> -Shali
>
>
>
> On Thu, Aug 22, 2013 at 10:29 PM, David R. Herz <WPD@theherzes.com> wrote:
>
> http://code.webplatform.org/gist/6288803
>
>
>
> Opera
>
> Version information
>
> Version
>
> 12.16
>
> Build
>
> 1860
>
> Platform
>
> Win32
>
> System
>
> Windows XP
>
> Browser identification
>
>
>
> Opera/9.80 (Windows NT 5.1; MRA 8.0 (build 5989)) Presto/2.12.388
Version/12.16
>
>
>
> David R. Herz
>
> wpd@theherzes.com
>
>
>
> From: Shali Nguyen [mailto:shalinguyen@gmail.com]
> Sent: Friday, August 23, 2013 2:41 AM
> To: wpd@theherzes.com
> Cc: Scott Rowe; public-webplatform@w3.org
> Subject: Re: Column examples
>
>
>
> Yay! Awesome! Thanks for adding those Scott. I created an account the
other day and will go ahead and work on examples for visibility and
word-break (moving them or improving codelets).
>
>
>
> David - which example came out to 5 columns for you and which OS/browser
are you viewing?
>
>
>
> Thanks for the warm welcome! I'm excited to contribute where possible. :)
Please let me know if you guys need any help on the visual design front as
well.
>
>
>
>
>
> --
> Shali Nguyen
> www.shalinguyen.com
> follow me @shalinguyen
> AIM: shalinguyen
>
>
>
> On Thu, Aug 22, 2013 at 2:40 PM, David R. Herz <WPD@theherzes.com> wrote:
>
> I looked at the columns and the examples come out five columns.  Had I
known how to fix it, I would have.
>
>
>
> David R. Herz
>
> wpd@theherzes.com
>
>
>
> From: Scott Rowe [mailto:scottrowe@google.com]
> Sent: Thursday, August 22, 2013 10:45 PM
> To: Shali Nguyen
> Cc: public-webplatform@w3.org
> Subject: Re: Column examples
>
>
>
> That's what I get for hitting the send button too soon...
>
>
>
> On Thu, Aug 22, 2013 at 12:24 PM, Scott Rowe <scottrowe@google.com> wrote:
>
> Thanks Shali!!!
>
>
>
> Great work here. Let me first reply in-line to some of your points...
>
>
>
> On Tue, Aug 20, 2013 at 5:38 PM, Shali Nguyen <shalinguyen@gmail.com>
wrote:
>
> Hi there!
>
> I was going through the webplatform.org docs today and became immediately
interested. I've been wanting to find a way to help contribute to the
community and would love to lend a hand!
>
> I plan on hopping in on tomorrow morning's meeting but wanted to try and
get started to see if I could be of help. Upon reviewing "columns" article
from the Aug 14th week, it looks like you guys are missing some examples
and have some that exist that aren't formatted cross browser w/vendor
prefixes.
>
> Here are my suggested improvements on live examples for Multi-column
sections:
>
> http://docs.webplatform.org/wiki/css/properties/columns
> Currently has no live example.
>
> Existing example: None
> New example: http://code.webplatform.org/gist/6288803
>
> Nice! I've added this to the document.
>
>
>
> http://docs.webplatform.org/wiki/css/properties/column-count
> Existing live example doesn't show column-count. I've created a simpler
example for only the column-count property.
>
> Existing example: http://code.webplatform.org/gist/5305530
> New example: http://code.webplatform.org/gist/6288917
>
> I've added this one, too.
>
>
>
> http://docs.webplatform.org/wiki/css/properties/column-rule
> Currently has no live example.
>
> Existing example: None
> New example: http://code.webplatform.org/gist/6288958
>
> and this one.
>
>
>
> http://docs.webplatform.org/wiki/css/properties/column-rule-color
> Currently has no live example.
>
> Existing example: None
> Propose to use this existing example:
http://code.webplatform.org/gist/6288958 (same column-rule above)
>
> I forked your example and broke out the column-rule-color property. See
http://code.webplatform.org/gist/6311315
>
> And I updated the doc.
>
>
>
> http://docs.webplatform.org/wiki/css/properties/column-rule-width
> Uses jsfiddle example instead of codelet.
>
> Existing example: http://jsfiddle.net/dstorey/K6X54/
> Propose to use this existing example:
http://code.webplatform.org/gist/6288958 (same column-rule above)
>
> I forked your example and broke out the column-rule-width property. See
http://code.webplatform.org/gist/6311393
>
> And I updated the doc.
>
>
>
> http://docs.webplatform.org/wiki/css/properties/column-rule-style
> Uses an example only visible in firefox.
>
> Existing example: http://code.webplatform.org/gist/5305898
> Propose to use this existing example:
http://code.webplatform.org/gist/6288958 (same column-rule above)
>
> I forked your example and broke out the column-rule-style property. See
http://code.webplatform.org/gist/6311519
>
> And I updated the doc.
>
> It looks like column-fill and column-gap examples are fine unless we want
to make sure vendor prefixes are also included. If that's the case, here is
the updated example (forked from existing example):
http://code.webplatform.org/gist/6289096
>
>
>
>
>
> Yeah, these looked okay. I'm not sure we need the prefixes, though I've
left them in all your examples. It's a nice touch, so why not. It's just
that most developers are sick of prefixes and we're all looking forward to
them going the way of the dodo.
>
>
>
> But hey, you don't need me to do this editing for you. Go ahead and
create an account:
>
>
http://docs.webplatform.org/w/index.php?title=Special:UserLogin&returnto=css&type=signup
>
>
>
> And dive right in, edit away!
>
>
>
> If you've got some more time this week, check out the list of properties
we're currently working on; see the Web Platform Wednesday page:
> http://docs.webplatform.org/wiki/Meta:web_platform_wednesday
>
>
>
> This page has more information on how to go about editing CSS properties,
with links to the editing guide and a rather amateurish tutorial video by
yours truly. (I'd appreciate any feedback on the video.)
>
>
>
> We're going to continue working on CSS properties in coming weeks, as
well. We hope you can join us!
>
>
>
>
>
> --
> Shali Nguyen
> www.shalinguyen.com
> follow me @shalinguyen
> AIM: shalinguyen
>
>
>
>
>
> Welcome aboard, Shali! We really appreciate the help!
>
> ~Scott
>
>
>
>
>
>
>
>
>
>
>
>
>
> --
> Shali Nguyen
> www.shalinguyen.com
> follow me @shalinguyen
> AIM: shalinguyen




--
Shali Nguyen
www.shalinguyen.com
follow me @shalinguyen
AIM: shalinguyen