Refresh HTML manual/API docs style#12868
Conversation
|
Suggestion: please attach a before screenshot for easy comparison. So it can be compared visually with the after screenshot you posted. This way we don't need to actually go to the site to compare with this. Also screenshot to screenshot comparison is easier since the size, dpi, color temperature etc. would be the same in both. |
|
After further reducing the top border of each item: 
|
|
That's a big improvement IMO. The top border clearly delineates items and communicates that I should be reading the description below and not above, currently only indicated by slightly more whitespace below descriptions. Though I'd use The screenshot still shows odd alignment of the description and "Raises" warnings, I think aligning them both with
|
|
Thanks! Adjusted description items left margin: 
|
|
Awesome, thanks! Removed from Makefile, and no wonder I couldn't find that file in the repo. |
SGrondin
left a comment
SGrondin
left a comment
There was a problem hiding this comment.
With the Makefile change it looks good to me
yawaramin
changed the title
|
Looks like the manual and API docs styles are entangled. Need to fix this first. 
|
yawaramin
changed the title
|
Manual: 
API docs: 
|
|
For code blocks in the manual I don't understand why you are adding a top border. In the doc it makes sense because the item is always related to the doc that follows, not to the content before, so you add a visual separator above. But this is not true for arbitrary code blocks in the manual, including in the examples in your screenshot -- |
|
I guess for consistency with the API docs, but you have a point that the delineation separates the prose from its related code. How about a bottom border instead? I feel like some structure in the code formatting is helpful. 
|
|
Thanks for the changes. The changes look good to me for my non-expert eyes. I think we want to avoid visible horizontal lines as delimiters on the manual side, both top and bottom since the code Looking at ocaml.org for another inspiration, the tutorial are using round border (but with syntactic color highlighting). |
|
Thanks @Octachron for the review. I'm not terribly attached to the borders so just removed them for the manual. Now it looks like this: 
|
gasche
left a comment
gasche
left a comment
There was a problem hiding this comment.
The result looks good to me now. Approved.
There are a few places in the code where the PR appears to break indentation, could you fix them?
Can you clean the history to avoid the back-and-forth?
| background-color: #edbf84;} | ||
| background-color: white; | ||
| text-decoration: underline; | ||
| } |
There was a problem hiding this comment.
nit: the identation looks off here
|
|
||
| pre{ | ||
| background:linear-gradient(to left,#fff 0,#ede8e5 100%) | ||
| background-color: #ede8e5; |
| border-radius: 1px; | ||
| /*border-bottom: 4px solid rgb(255, 215, 181);*/ | ||
| box-shadow: 0 4px 0 0px rgb(255, 215, 181); | ||
| background-color:#ffd6b5; |
Simplify colours and get rid of gradients. Also fix search button icon.
yawaramin
force-pushed
the
simpler-doc-style
branch
from
5a8364c to
323c8b3
Compare
|
@gasche sure, did the requested clean-ups. |
|
@Octachron do you want to have another round of feedback? Otherwise please feel free to merge. |
|
(It would be nice to have the changes in the 5.2 version of the manual) |
| onclick = "this.oninput();" | ||
| onpaste = "this.oninput();"> | ||
| <img src="search_icon.svg" alt="Search" class="api_search svg" onclick="mySearch(%b)">%s</div> | ||
| <button title="Search" onclick="mySearch(%b)" style="cursor:pointer">🔎</button> %s</div> |
There was a problem hiding this comment.
This raises a small concern in term of accessibility. I wonder if replacing 🔎 with
<span aria-hidden="true">🔎</span>Searchwould not be better?
There was a problem hiding this comment.
Thanks for the suggestion, I've just done this. Looks like:
|
Merged, thanks! |
6 participants
Simplify colours and get rid of gradients. Also fix search button icon.
Before:
After: