Closed
Bug 1102508
Opened 10 years ago
Closed 9 years ago
Add to syntax boxes a link to an article explaining how to interpret them
Categories
(developer.mozilla.org Graveyard :: Design, enhancement)
Tracking
(Not tracked)
RESOLVED
FIXED
People
(Reporter: shobson, Assigned: shobson)
Details
Attachments
(3 files)
In places where an article contains syntax it would be helpful to users to link to an article explaining how to read syntax. For example: https://developer.mozilla.org/en-US/docs/Web/CSS/transform This will help new users understand our content and how the technology they're trying to use works. = Option 1 Add a link to the syntax article whenever a <pre> with a class of .syntax and .twopartsyntaxbox is detected. Pros: - it would appear only on :hover or :focus, not getting in the way of current content - it would apply immediately to all places we have syntax currently Cons: - not visible, does not encourage users to engage - we can use a combination of things to guess at what language the syntax is for, but we will be guess wrong some times (those places could be corrected manually) = Option 2 Prevent prism from styling <pre>s with a class of .syntaxbox and .twopartsyntaxbox which would allow links to appear in this content. When used this macro https://developer.mozilla.org/en-US/docs/Template:csssyntax generates links and tooltips explaining how each part of the syntax works however those links are being stripped out when prism.js formats them Pros: - each part of the syntax is explained - hit area is very small on mobile, tool tips don't display on mobile Cons: - these links only appear when the macro has been used to generate the syntax and there are many places where it has not - no prism.js formatting on syntax (this would only effect a few small places because most syntax boxes do not have a prism brush being defined so they are being styled the fallback - HTML, but we have almost no HTML in syntax boxes) = Questions I'd like to implement option #1 immediately, is that okay? Do we want to also implement option #2? I think so. = Attachments will be added showing both these options. This hasn't been identified as a priority so I can't do too much additional work on it but both of these options can be achieved in a morning ;) Thanks to :teoli and :sheppy for providing me with background info to get to this point.
Assignee | ||
Comment 1•10 years ago
|
||
Assignee | ||
Comment 2•10 years ago
|
||
Assignee | ||
Updated•10 years ago
|
Flags: needinfo?(jypenator)
Flags: needinfo?(eshepherd)
Assignee | ||
Updated•10 years ago
|
Assignee: nobody → shobson
Updated•10 years ago
|
Severity: normal → enhancement
Component: General → Design
Comment 3•9 years ago
|
||
Jean-Yves -- IIRC you were going to write up an overview piece that could be used for this purpose. Do I remember that correctoy, or am I hallucinating? :)
Flags: needinfo?(eshepherd)
Updated•9 years ago
|
Flags: needinfo?(jypenator)
Summary: Link syntax to articles on how to read syntax → Add to syntax boxes a link to an article explaining how to interpret them
Assignee | ||
Comment 4•9 years ago
|
||
I identified this article as the place to link CSS syntax: https://developer.mozilla.org/en-US/docs/Web/CSS/Value_definition_syntax Which might be the one sheppy is thinking of. I've also identified 2 other kinds of syntax we could add the link to (JavaScript and HTML) but those would need to go to other articles which I don't think exist.
Comment 5•9 years ago
|
||
It is the right article that the different symbol links to. Btw, to answer the question, we should do 1 and 2. But I don't think there is a formal grammar used in JS and HTML so there is nothing to point to.
Comment 6•9 years ago
|
||
(In reply to Stephanie Hobson [:shobson] from comment #4) > I identified this article as the place to link CSS syntax: > https://developer.mozilla.org/en-US/docs/Web/CSS/Value_definition_syntax > Which might be the one sheppy is thinking of. Yes, that's the page you should be linking to for CSS pages. > I've also identified 2 other kinds of syntax we could add the link to > (JavaScript and HTML) but those would need to go to other articles which I > don't think exist. They don't; our "syntax" boxes for JavaScript are really just examples, and on HTML pages, we don't really present a syntax at all. We just present the name of the element, then a list of the attributes and their possible values, with notes about details like when one attribute requires the use of another, etc. It may maek sense to move to a formal syntax presentation for either or both of JS and HTML, but for now, let's just get this bug wrapped for CSS.
Comment 7•9 years ago
|
||
Commits pushed to master at https://github.com/mozilla/kuma https://github.com/mozilla/kuma/commit/18b07e6ccd6002efb8c81133b2cfedaf9a5b1c64 Fix Bug 1102508: Link Syntax to Syntax Help Article Added javascript to detect syntaxbox and twopartsyntaxbox and create a link to help articles based on if there is a CSS class identifying the language, falling back to the language the section is in if there is not. Added CSS to style the link. https://github.com/mozilla/kuma/commit/a74d74840cc2a015b839b3cb206f8cb89b47fd40 Fix Bug 1102508: Link Syntax to Syntax Help Article Prevent prism from styling syntaxbox and twopartysyntaxbox so that we can link the syntax to articles explaining it. Update styles so they're still styled correctly without prism. https://github.com/mozilla/kuma/commit/36ffa14f771a63c921dc7d6daf34fff1735db20e Merge pull request #2953 from stephaniehobson/BUG-1102508-syntax Fix Bug 1102508: Link syntaxboxes to Syntax Help Article
Updated•9 years ago
|
Status: NEW → RESOLVED
Closed: 9 years ago
Resolution: --- → FIXED
Updated•4 years ago
|
Product: developer.mozilla.org → developer.mozilla.org Graveyard
You need to log in
before you can comment on or make changes to this bug.
Description
•