Repository navigation
Use a more resilient mechanism for showing the icons on the Icons page #11073
Description
The source code for icons.dart looks like this:
/// <p><i class="material-icons md-36">4k</i> — material icon named "4k".</p>
static const IconData four_k = const IconData(0xe072, fontFamily: 'MaterialIcons');
/// <p><i class="material-icons md-36">ac_unit</i> — material icon named "ac unit".</p>
static const IconData ac_unit = const IconData(0xeb3b, fontFamily: 'MaterialIcons');
/// <p><i class="material-icons md-36">access_alarm</i> — material icon named "access alarm".</p>
static const IconData access_alarm = const IconData(0xe190, fontFamily: 'MaterialIcons');This HTML shows up in the IDE:
I don't know what's expected here - even if I was able to get the IDE tooltips to handle the HTML (though the docs say avoid HTML) the icons wouldn't render correctly because the CSS isn't being loaded in the tooltips.
Activity
[-]Material icons contain HTML in comments[/-][+]Material icons contain HTML in doc comments which get rendered in the IDE[/+]Hixie commentedon May 1, 2018
This seems like an IDE problem? :-)
@DanTup I'm going to close this since I'm not sure what you want us to change, but please don't hesitate to reach out to me if you want to discuss his further. We should definitely find a way to make it work in all our IDEs!
DanTup commentedon May 2, 2018
TL;DR: I still thing this is valid and should be addressed.
My suggestion is that we should not have HTML inside the comments in the source code where possible. The docs say to avoid it (though avoid is a wooly term). In this case, even if the IDE could render HTML, these HTML chunks required a specific stylesheet/font to be loaded to work, which is even less likely to be available to an IDE in its tooltips.
What would be better is having MarkDown image tags, like the colours code does:
This has no requirement for CSS/fonts and should work anywhere that is rendering Markdown correctly. The images are already available online (though these are transparent so might not play nice in light/dark themes - maybe we should have copies; it'd also remove reliance on them staying at these urls?):
https://storage.googleapis.com/material-icons/external-assets/v4/icons/svg/ic_ac_unit_white_36px.svg
https://storage.googleapis.com/material-icons/external-assets/v4/icons/svg/ic_ac_unit_black_36px.svg
For now, I'm working around this in Dart Code by regexing them out and replacing with a markdown image tag; but it could break if this HTML changes.
FWIW, IntelliJ/AS don't render these properly either - they strip the HTML but leave the text, so you just get this weird label/alt text:
Hixie commentedon May 3, 2018
Using images is a non-starter, because of this page:
https://master-docs-flutter-io.firebaseapp.com/flutter/material/Icons-class.html
Using the font is what we want, but I agree that the current mechanism isn't good.
@jcollins-g do you have any suggestions for how we could mark up these cases so that they work both in the HTML output and in IDEs? It's ok if it requires work on the IDE side, but it needs to be something more resilient than relying on a magic HTML sequence that happens to trigger some CSS.
cc @devoncarew
[-]Material icons contain HTML in doc comments which get rendered in the IDE[/-][+]Use a more resilient mechanism for showing the icons on the Icons page[/+]jcollins-g commentedon May 3, 2018
@Hixie Why are images are a non-starter here? The example @DanTup gave seems not particularly worse than the situation in class Icons from a coding perspective, and it would definitely render similarly across.
However, assuming they are a nonstarter for reasons @Hixie is about to explain to me, there's always the potential for more magical Dartdoc-only strings, as scary as that can be sometimes. Maybe something like this:
The challenge for dartdoc here is to do this in a way that's not accumulating large amounts of hardcoding. Probably would want to have a configurable mapping of style name to Markdown/HTML wrapping code, e.g.:
{ 'material-icons': '<i class="material-icons md-36">%s%</i>' }or some such thing. A few of these mappings would be supported by Dartdoc's default style; others would need to be added by users of the style sheet. Dartdoc's new configuration system at least will make this less ugly than it otherwise would be.
However, I have no idea how hard it would be to implement this in an IDE -- it might be easier than it would be to do magical CSS inference though. It's possible we could have style snippets defined for each of the supported
@styletags in dartdoc's config, and maybe the IDE could read it.As an aside, if there are too many more of these magical dartdoc directives added at some point I'll want to turn this into a real parser/language but we haven't quite hit critical mass there yet. In general, the parsing and interpretation of dartdoc-specific markdown hacks^H^H^H^H^Hextensions probably needs dartdoc integrated more strongly with the analyzer (e.g. a dartdoc analyzer plugin). So anything we do here is going to be at least a little ugly.
DanTup commentedon May 4, 2018
I was going to ask the same; they're already used for the colours? It seems like the least effort to implement on both sides to me (neither the website nor the IDE would need to do anything).
I'm not sure I understand what you're proposing, but we can't rely on any CSS classes or fonts in VS Code (and I expect that applies to all IDEs - IntelliJ isn't HTML-based so probably also cannot). So we'd still be left having to regex things out; which is only slightly better than what we have today (in that it might be slightly less fragile).
jcollins-g commentedon May 4, 2018
@DanTup I was hypothesizing that there might be something we could have as a common definition of what these magic strings mean. Maybe a yaml/json table mapping them out to formatting information. That could be snippets of CSS, HTML, markdown, or what have you. Then that can be read by the IDEs and dartdoc to generate common behavior by substituting strings. So it's still regexps, but at least all the uglyness about what they meant would be shared across platforms.
DanTup commentedon May 4, 2018
Gotcha. I still personally think (markdown) images would be perfect; the docs are already markdown so whoever is consuming them is already handling that. Markdown image tags (as used in colours) just work for free without anyone needing to do custom parsing of the dartdocs.
jcollins-g commentedon May 4, 2018
Markdown images make a lot of sense to me too. I'm interested to hear why @Hixie thinks they are not viable.
devoncarew commentedon May 4, 2018
For IntelliJ, we special case knowledge of Flutter colors and Icons, and have generated material icons in the flutter-intellij repo (we rely more on analyzing the code then annotations in the comments).
12 remaining items
markusaksli-nc commentedon Jul 17, 2020
Hi @Hixie
This issue no longer seems relevant in Intellij IDEA 2020.2, Android Studio 4.0.1, and VS Code 1.47.
Should it still remain open?
Thank you
DanTup commentedon Jul 20, 2020
Currently VS Code is handling this by using regular expressions to extract the HTML code:
This works, but isn't ideal. If that HTML changes in the source (which it has in the past), the VS Code previews will break until the regex is updated (and released) - the regex may also need to support multiple SDK versions at the same time.
There are other editors rendering this that probably don't do the same regex - actually, this reminds me that the LSP server doesn't, so this will regress in VS Code if we don't fix it there (which will involve putting this regex in another place).
I don't think it's a big problem, but it would still be nice to have something better.
guidezpl commentedon Mar 16, 2023
Working on #102560 at the moment, which will be in a 3P package, and HTML + CSS really seems like the ideal solution. A couple CSS files is all you need to display all icons.
I know there are some limitations for VS Code to work around, but still think we can avoid some pitfalls like having to manage 6000 (yes, up from 1970) .pngs, or committing any static files at all.
In any case, I think this issue can be closed, since work relating to IDEs at dart-lang/sdk#47667.