1106768 - CSS property templates don't allow defining @-rule descriptors

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: Macros/Templates, defect)

Description

[Sebastian Zartner [:sebo]]

What did you do?
================
I defined the items for the viewport descriptors[1][2] and reference them within the descriptor definition pages like e.g. min-zoom[3] via the cssbox() template.

Their names were defined like "@viewport/min-zoom" to indicate that they are descriptors of @viewport.
(Mainly did that in order to be able to define the width and height descriptors independently from the normal width and height properties.)

What happened?
==============
The data could not be referenced within the descriptor pages. Got errors like this one:

'Value 'initial-min-zoom' not found in DB*'

What should have happened?
==========================
I should be able to reference @-rule descriptors via cssbox().

Is there anything else we should know?
======================================
[1] https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_values_syntax#Device_Adaption
[2] http://dev.w3.org/csswg/css-device-adapt/
[3] https://developer.mozilla.org/en-US/docs/Web/CSS/@viewport/min-zoom

Comment 1

[Jean-Yves Perrier [:teoli]]

Moving components as cssbox is controlled by the content team and not by the devs.

Does descriptors have the same entries in the "CSS box" as properties?

Wouldn't it be better to have a CSSDescriptorBox (would all descriptors have the same fields there) ?

Comment 2

[Sebastian Zartner [:sebo]]

(In reply to Jean-Yves Perrier [:teoli] from comment #1)
> Does descriptors have the same entries in the "CSS box" as properties?
> 
> Wouldn't it be better to have a CSSDescriptorBox (would all descriptors have
> the same fields there) ?
Actually they do not have all entries properties have, e.g. they do not apply to anything. So you're right.
So what should we do with this issue then?

Sebastian

Comment 3

[Jean-Yves Perrier [:teoli]]

I've launch a broader discussion on descriptors on dev-mdc. Once settled, we will be able to move forward here.

:-)

Comment 4

[Sebastian Zartner [:sebo]]

(In reply to Jean-Yves Perrier [:teoli] from comment #3)
> I've launch a broader discussion on descriptors on dev-mdc.

For reference, here's the link to that discussion:
https://groups.google.com/forum/#!topic/mozilla.dev.mdc/y6TemmIP16A

> Once settled, we will be able to move forward here.

As there were no further comments on that topic can I start working on it?

Sebastian

Comment 5

[Jean-Yves Perrier [:teoli]]

Yes, of course!

Comment 6

[Sebastian Zartner [:sebo]]

I started working on this and created the descriptor info page[1] and the related template[2]. See the @viewport min-zoom descriptor[3] for an example.

I assigned a new class 'cssdescriptor' to the descriptor box, which currently doesn't exist. So there are three solutions to style this box:

- Add '.cssdescriptor' to the rules applying to CSS property info boxes, so both are styled the same way.
- Create new rules for CSS descriptor boxes to style them differently.
- Reuse the 'cssprop' class for descriptors to avoid having to change the CSS (and accept that the class name doesn't fit).

So what option should we choose?

Also please give feedback on whether the current solution needs changes.

Sebastian

[1] https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_descriptor_definition
[2] https://developer.mozilla.org/en-US/docs/Template:cssdescriptorinfo
[3] https://developer.mozilla.org/en-US/docs/Web/CSS/@viewport/min-zoom

Comment 7

[Sebastian Zartner [:sebo]]

(In reply to Sebastian Zartner [:sebo] from comment #6)
> [1] https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_descriptor_definition
> [2] https://developer.mozilla.org/en-US/docs/Template:cssdescriptorinfo

With the new cssinfo (bug 1198963) and csssyntax2 templates, which make use of the JSON DB including the descriptor info, we don't need the cssdescriptorinfo template and the CSS_descriptor_definition page anymore. So they should be removed (bug 1199210) resp. redirected (bug 1199204).

> I assigned a new class 'cssdescriptor' to the descriptor box, which
> currently doesn't exist. So there are three solutions to style this box:
> 
> - Add '.cssdescriptor' to the rules applying to CSS property info boxes, so
> both are styled the same way.
> - Create new rules for CSS descriptor boxes to style them differently.
> - Reuse the 'cssprop' class for descriptors to avoid having to change the
> CSS (and accept that the class name doesn't fit).
> 
> So what option should we choose?

An answer to this question is still pending. Jean-Yves?

Sebastian

Comment 8

[Jean-Yves Perrier [:teoli]]

I would say reuse cssprop for the short term. Stephanie has a mid-term plan to make CSS class names more OO-CSS and I think we could sync a bit to save overall work (as we will regenerate all the pages using .cssprop at the end of the current project).

Maybe this plan could be followed:

1. Create and push to prod a OO-CSS replacement for .cssprop [1], .htmlelt [2], .audionodebox [3] that will also suite our event pages [4]. (without killing .cssprop, .htmlelmt, .audionodebox in CSS yet)
2. Update the {{csssyntax}} to use it (Sebastian is updating it anyway).
3. In parallel, or not, we can also update macros using .htmlelt and .audionodebox (1 each, pretty straightforward).
4. In one go, or separately for each macro, regenerate the pages using them (will happen anyway for CSS pages, and the others are not that numerous so these can be done in about 1h).
5. Once the pages are regenerated, remove .cssprop, .htmlelmt, .audionodebox from the CSS.

Note1: that we can also update the HTML generated by these macros in the process, if needed.
Note2: in the CSS, I also see .summary-box-events and .summary-box-js. I don't know if they are in use right now (Florian will likely know for the second)
Note3: we likely need a meta bug for the whole OO-CSS work, where we can list macros to update and do it little by little.

Doing this work now will save us to regenerate twice the 400 affected CSS pages, at the expense of updating the CSS this month (additional dependency).

Ni/ Florian, Stephanie for feedback on this potential plan.

[1] Example of use: https://developer.mozilla.org/en-US/docs/Web/CSS/list-style-type
[2] Example of use: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/keygen
[3] Example of use: https://developer.mozilla.org/en-US/docs/Web/API/StereoPannerNode
[4] Example of future use: https://developer.mozilla.org/en-US/docs/Web/Events/touchstart

Comment 9

[Jean-Yves Perrier [:teoli]]

Of course, it isn't {{csssyntax}} but {{cssbox}} in the text of the previous comment. Sorry.

Comment 10

[Sebastian Zartner [:sebo]]

(In reply to Jean-Yves Perrier [:teoli] from comment #8)
> I would say reuse cssprop for the short term. Stephanie has a mid-term plan
> to make CSS class names more OO-CSS and I think we could sync a bit to save
> overall work (as we will regenerate all the pages using .cssprop at the end
> of the current project).

Fine for me.

> Maybe this plan could be followed:
> 
> 1. Create and push to prod a OO-CSS replacement for .cssprop [1], .htmlelt
> [2], .audionodebox [3] that will also suite our event pages [4]. (without
> killing .cssprop, .htmlelmt, .audionodebox in CSS yet)
> 2. Update the {{csssyntax}} to use it (Sebastian is updating it anyway).
> 3. In parallel, or not, we can also update macros using .htmlelt and
> .audionodebox (1 each, pretty straightforward).
> 4. In one go, or separately for each macro, regenerate the pages using them
> (will happen anyway for CSS pages, and the others are not that numerous so
> these can be done in about 1h).
> 5. Once the pages are regenerated, remove .cssprop, .htmlelmt, .audionodebox
> from the CSS.
> 
> ...
>
> Note3: we likely need a meta bug for the whole OO-CSS work, where we can
> list macros to update and do it little by little.

Stephanie, when you create that OO-CSS bug, could you please CC me?

> Doing this work now will save us to regenerate twice the 400 affected CSS
> pages, at the expense of updating the CSS this month (additional dependency).
> 
> Ni/ Florian, Stephanie for feedback on this potential plan.

At least to me it sounds good. FYI, I will update every CSS page using {{cssbox}} once I'm finished with bug 1198963.

(In reply to Jean-Yves Perrier [:teoli] from comment #9)
> Of course, it isn't {{csssyntax}} but {{cssbox}} in the text of the previous
> comment. Sorry.

To be 100% correct, it is {{cssinfo}}, replacing {{cssbox}}.

Sebastian

Comment 11

[Florian Scholz (Open Web Docs)]

(In reply to Jean-Yves Perrier [:teoli] from comment #8)
> Note2: in the CSS, I also see .summary-box-events and .summary-box-js. I
> don't know if they are in use right now (Florian will likely know for the
> second)

I am not aware of using a class called .summary-box-js. Haven't researched in detail, though.

> Doing this work now will save us to regenerate twice the 400 affected CSS
> pages, at the expense of updating the CSS this month (additional dependency).
> 
> Ni/ Florian, Stephanie for feedback on this potential plan.

Sounds good to me.

Comment 12

[Stephanie Hobson [:shobson]]

Everything in comment 8. Yes! So much!

Currently the classes I have identified as "summary boxes" are:

.cssprop
.htmlelt
.audionodebox
.summary-box-js
.summary-box-events

I would be very happy to replace them all with .summary-box 

>> Note1: that we can also update the HTML generated by these macros in the process, if needed.

Jeremie was working on changing the htmlelt boxes to use a table structure instead of a list with definition elements. Both approaches are okay with me semantically but I only want to have to style one of them :P

Once it's standardized I can do some extra work to make sure it's more mobile friendly.

> Note3: we likely need a meta bug for the whole OO-CSS work, where we can list macros to update and do it little by little.

I've been working under Bug 1070001, feel free to file blockers on that. Bug 1018707 also has a link to an amazing ether pad that has a good start for categorizing the classes.

I don't have official sanction to work on this yet so it's all very off the side of my desk.

Comment 13

[Sebastian Zartner [:sebo]]

(In reply to Stephanie Hobson [:shobson] from comment #12)
> Everything in comment 8. Yes! So much!
> 
> Currently the classes I have identified as "summary boxes" are:
> 
> .cssprop
> .htmlelt
> .audionodebox
> .summary-box-js
> .summary-box-events
> 
> I would be very happy to replace them all with .summary-box

To keep the naming constant (named the new template 'cssinfo'), I suggest to call it .info-box.

> >> Note1: that we can also update the HTML generated by these macros in the process, if needed.
> 
> Jeremie was working on changing the htmlelt boxes to use a table structure
> instead of a list with definition elements.

What's the reason behind that?

> Both approaches are okay with me semantically but I only want to have to style one of them :P

Sure, that's why we should keep those unified. I imagine to have one macro covering all cases in the end. That macro would take a JSON and generate the list/table from it.

Sebastian

Comment 14

[Stephanie Hobson [:shobson]]

> > >> Note1: that we can also update the HTML generated by these macros in the process, if needed.
> > 
> > Jeremie was working on changing the htmlelt boxes to use a table structure
> > instead of a list with definition elements.
> 
> What's the reason behind that?

Jeremie?

Comment 15

[Jeremie Patonnier :Jeremie]

(In reply to Stephanie Hobson [:shobson] from comment #14)
> > >> Note1: that we can also update the HTML generated by these macros in the process, if needed.
> > 
> > Jeremie was working on changing the htmlelt boxes to use a table structure
> > instead of a list with definition elements.
> 
> What's the reason behind that?

Semantics.
It looks like at table and it contains obvious tabular data (and certainly not definitions), therefor it should be a table.

Comment 16

[Sebastian Zartner [:sebo]]

(In reply to Jeremie Patonnier :Jeremie from comment #15)
> (In reply to Stephanie Hobson [:shobson] from comment #14)
> > > >> Note1: that we can also update the HTML generated by these macros in the process, if needed.
> > > 
> > > Jeremie was working on changing the htmlelt boxes to use a table structure
> > > instead of a list with definition elements.
> > 
> > What's the reason behind that?
> 
> Semantics.
> It looks like at table and it contains obvious tabular data (and certainly
> not definitions), therefor it should be a table.

Fine for me.

Unfortunately we hijacked this bug for our discussion.
Anyway, according to the steps described by Jean-Yves in comment 8 I created bug 1207335 now to track the CSS changes, bug 1207344 for changing the template(s) and pages and bug 1207352 to remove the old classes in the end.

Sebastian