Re: Column examples

I coulda swore I hit 'reply-all' but nay. Here we go again...


On Mon, Aug 26, 2013 at 9:38 AM, Scott Rowe <scottrowe@google.com> wrote:

> Thanks Shali! Great work here. We really appreciate you're being so
> meticulous! I'll answer questions in-line:
>
>
> On Sun, Aug 25, 2013 at 11:00 AM, Shali Nguyen <shalinguyen@gmail.com>wrote:
>
>> 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
>>
>
> Looking good!
>
>
>>
>> *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."*
>>
>>
> Good decision. The only gnit I'd add would be to link to the column-width
> and column-count properties in the summary.
>
>
>> 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?
>>
>
> While I like the "Formal Syntax" approach, I have to lean toward
> consistency and against changing horses in mid-stream, what with us being
> so close to finishing this project. Let's follow the example we have with
> the border property (
> http://docs.webplatform.org/wiki/css/properties/border) where the values
> for the shorthand property are all listed on one line, and "inherit" is
> listed separately. This connotes the formal syntax and communicates the
> usage options sufficiently.
>
>
>>
>> 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.
>>
>
> Any time you find yourself in this situation, ask what would the user
> prefer? As a user, please spare me another click and wading through another
> explanation. We should provide as much information as the user needs to use
> the property in the documentation for that property. Also, we approach the
> shorthand properties as being the "primary" usage for a given family of
> properties, so the explanation there should be the most elaborate. This is
> also why we suggest that authors start with the shorthand property, then
> cut-and-paste from there into the individual (long-hand) properties.
>
> Again, use the border (
> http://docs.webplatform.org/wiki/css/properties/border) property as an
> example. The explanation is included for each value. (My gnit here is that
> there should also be links to things like "standard length units" so I
> don't have to go digging around for those, but I'll deal with this in the
> border property myself.)
>
> Does this work for everyone? Shali? Did I miss anything?
>
>
>>
>> -----
>>
>> 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
>>
>>
> Indeed, this is looking much better. We really appreciate your patience in
> going back-and-forth with all of this, Shali. The process, as you have well
> discovered, is not always straight-forward, and the best solution comes
> from clear communication. Thanks for taking the time to do this right!
>
> ~Scott
>
>
>
>>
>>
>>
>>
>> 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
>>
>
>