General formatting improvements in the spec #3984
Conversation
gourlaysama
force-pushed
the
wip/spec
branch
from
d5f8b20
to
7ab96f1
Compare
|
PLS REBUILD/pr-scala@e11fe9b |
|
(kitty-note-to-self: ignore 55616510) |
|
PLS REBUILD/pr-scala@e11fe9b |
|
(kitty-note-to-self: ignore 55710532) |
|
PLS SYNCH |
|
(kitty-note-to-self: ignore 55844967) |
|
The code blocks exemplifiying the named arguments transformation are not displayed on a single line. Before:
After:
|
|
I'm looking at the W3C link checker's report on your published static site. Looking quite good now! Here's one wrong link out to Scaladoc: We still generate duplicate anchors, particular for examples. e.g in section 3, Types:
I see you changed section titles to avoid this problem when we needed to link to an example. I guess we can leave the untargetted examples as is for now (rather than coming up with unique names for them.) |
|
Overall, this is an amazing contribution. Thank you, Antoine! |
This adds syntax highlighting for all code scala blocks. Highlighting is done after MathJax is done rendering so that latex can be used in code blocks (and it currently *is* used). Sadly Scala isn't common enough to be bundled in the highlight.min.js available from CDNs, so we commit a local version of version 8.2 with only scala bundled in it. The only other language used (ebnf) isn't supported by highlight.js.
Two things worth mentioning:
- `\em` and `emph` are not supported by MathJax,
- and things like `\mathcal{C}_0` require escaping the `_`,
otherwise markdown sees it as the beginning of `_some string_`.
It doesn't happen without the closing bracket in front, e.g. in `b_0`.
For examples, the "name" of the example (like "Example Ordered") is only used to derived its html id so that one can link to it (see `layouts/default.yml`). Ideally all examples should have a name; here I only added enough to satisfy existing links.
gourlaysama
force-pushed
the
wip/spec
branch
from
7ab96f1
to
d24ad90
Compare
|
@retronym I fixed the code block problem and the various other comments. |
|
PLS REBUILD/pr-scala@6e19162 |
|
PLS REBUILD/pr-scala@d24ad90 |
|
(kitty-note-to-self: ignore 55896162) |
|
(kitty-note-to-self: ignore 55896181) |
|
@gourlaysama Looks nice. Just as a note regarding examples: It would be nice if we could get rid of the examples-as-headings approach, but after spending a few hours on it, it looks like Jekyll supports exactly those parsers which make this impossible. Two reasons for not having examples-as-headings:
Status quo is that I have given up on a real solution for now and just converted all Example headings to h6 headings, which I don't show in my spec fork anyway. Looks like the spec situation keeps regressing. |
|
PLS REBUILD/pr-scala@d24ad90 |
|
(kitty-note-to-self: ignore 55918698) |
|
LGTM, a big improvement to the state of the art. I would love to see a sidebar with navigation between sections. Any idea how to make that a reality? |
General formatting improvements in the spec
|
FYI, these changes are published to http://www.scala-lang.org/files/archive/spec/2.11/ (that happens automatically after merging). I needed to do a force browser refresh to see the code highlighting. I assume the browser was caching a Javascript resource that we'd updated in the PR. |
|
Me too. Maybe there's a place on the doc page for a notice. |
|
@retronym I'm looking into a navigation sidebar. It should be possible with some Jekyll and jQuery magic. @soc I agree examples as headings aren't great, but Markdown doesn't give a lot of options for encoding that kind of semantic information. At least it should be possible to keep them out the navigation. What kind of special formatting did you have in mind for code examples? |
|
@gourlaysama I settled on using block-quotes for now: http://oxnrtr.de/scala-spec/01-lexical-syntax.html (also note the navigation sidebar and the outline). That means block-quotes can't be used for anything else except examples anymore, but I haven't found another use-case for them anyway. |
The spec always needs some love, so here I go:
This is only about formatting, it does not change content or even wording.
I uploaded a preview of the result here to make reviewing easier.