doc: fix word wrapping for api stability boxes #14809

saadq · 2017-08-13T16:23:03Z

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc

This is meant to fix the issue that was opened here originally.

Fixes: nodejs/nodejs.org#1337

Before:

After:

silverwind · 2017-08-13T19:37:03Z

Is there a reason why these boxes are <pre>? Doesn't seem semantically correct to me, and the fact that they inherit rules targeting code blocks isn't ideal either.

I'd change them to <div> and add padding: 1em to them.

refack · 2017-08-13T20:04:13Z

Is there a reason why these boxes are <pre>? Doesn't seem semantically correct to me, and the fact that they inherit rules targeting code blocks isn't ideal either.

I think it's because it's rendered markdown. A simple style change might be to replace the ``` with >

or exclude pre[lang=txt] from the css

silverwind · 2017-08-13T20:36:37Z

@refack nope, they are generated by our own code:

node/tools/doc/html.js

Line 403 in 314217f

`<pre class="${classNames}"><a href="${docsUrl}">$1 $2</a>$3</pre>`

refack · 2017-08-13T21:43:00Z

Mostly enjoying the new code line quoting 👐

@refack nope, they are generated by our own code:

AFAICT that's the header for each API endpoint:

node/tools/doc/html.js

Line 33 in 314217f

const STABILITY_TEXT_REG_EXP = /(.*:)\s*(\d)([\s\S]*)/;

node/tools/doc/html.js

Lines 397 to 406 in 314217f

    
           function parseAPIHeader(text) { 
        
             const classNames = 'api_stability api_stability_$2'; 
        
             const docsUrl = 'documentation.html#documentation_stability_index'; 
        
             text = text.replace( 
        
               STABILITY_TEXT_REG_EXP, 
        
               `<pre class="${classNames}"><a href="${docsUrl}">$1 $2</a>$3</pre>` 
        
             ); 
        
             return text; 
        
           }

That maps:

node/doc/api/crypto.md

Lines 678 to 684 in 2e7ccc2

    
           ### ecdh.setPublicKey(publicKey[, encoding]) 
        
           <!-- YAML 
        
           added: v0.11.14 
        
           deprecated: v5.2.0 
        
           --> 
        
           > Stability: 0 - Deprecated

to:

Anyway let's do both: replace the markup and the rendering code

silverwind · 2017-08-13T23:22:20Z

@refack I'm still pretty sure that <pre> comes from there, the changelog (.api_metadata) is generated elsewhere.

Anyways, my suggestion to @saadq would be to replace the <pre> with a <div> in html.js and add padding: 1em to .api_stability in CSS.

saadq · 2017-08-14T03:31:58Z

I agree that pre probably wasn't that semantically correct, so I changed it to div as you suggested. However, this cause some stylistic issues:

After changing pre -> div

The font-weight became a lot bolder and the line-height became smaller, so I added a couple of styles to make it look like it did when it was still using pre.

After adding/removing some additional styles

Does this look alright to everyone?

silverwind

Looking fine to me, thanks.

TimothyGu · 2017-08-14T08:48:58Z

doc/api_assets/style.css

+  white-space: pre-wrap;
+  word-wrap: break-word;
+  padding: 1em;
+  line-height: 1.5;


Are these (esp. the font and wrapping ones) still necessary now that the container has been switched to a <div>?

Ahh, you're right. Since it's not pre anymore, the wrapping is no longer an issue. The padding and line-height are still necessary though.

I reverted the wrapping changes. Just to clarify, I don't know if the line-height is strictly "necessary", I just added it because that was what the pre had originally. I'm not sure if you all think it looks fine without it.

Without line-height:

With line-height:

I think I like it more with the extra space. Another option would be to make it a <p> which already sets 1.5em line-height and a similar margin-bottom, so you save two declarations.

Thought, it might be unexpected to have <p> and those boxes share CSS. So, LGTM as-is.

This reverts commit e0dcbd7.

A bunch of other people are looking at this more closely and with more expertise than I bring to CSS etc. Plus, my review is from a version of this PR that is now several iterations old. Dismissing my review and letting the knowledgable folks handle it instead. Thanks!

silverwind · 2017-08-15T16:30:44Z

doc/api_assets/style.css

+  white-space: pre-wrap;
+  word-wrap: break-word;
+  padding: 1em;
+  line-height: 1.5;


Thought, it might be unexpected to have <p> and those boxes share CSS. So, LGTM as-is.

tniessen · 2017-08-16T09:56:11Z

Landed in eab2bea.

PR-URL: #14809 Fixes: nodejs/nodejs.org#1337 Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]> Reviewed-By: Roman Reiss <[email protected]> Reviewed-By: Tobias Nießen <[email protected]>

PR-URL: nodejs/node#14809 Fixes: nodejs/nodejs.org#1337 Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]> Reviewed-By: Roman Reiss <[email protected]> Reviewed-By: Tobias Nießen <[email protected]>

PR-URL: #14809 Fixes: nodejs/nodejs.org#1337 Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]> Reviewed-By: Roman Reiss <[email protected]> Reviewed-By: Tobias Nießen <[email protected]>

doc: fix word wrapping for api stability boxes

e0dcbd7

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Aug 13, 2017

saadq mentioned this pull request Aug 13, 2017

stability index wrapping nodejs/nodejs.org#1337

Closed

gibfahn approved these changes Aug 13, 2017

View reviewed changes

Trott previously approved these changes Aug 13, 2017

View reviewed changes

lpinca approved these changes Aug 13, 2017

View reviewed changes

refack approved these changes Aug 13, 2017

View reviewed changes

jasnell approved these changes Aug 13, 2017

View reviewed changes

watilde approved these changes Aug 13, 2017

View reviewed changes

doc: use div instead of pre for api_stability

0a6fb2b

silverwind approved these changes Aug 14, 2017

View reviewed changes

TimothyGu reviewed Aug 14, 2017

View reviewed changes

Revert "doc: fix word wrapping for api stability boxes"

be1c7ca

This reverts commit e0dcbd7.

tniessen approved these changes Aug 14, 2017

View reviewed changes

silverwind approved these changes Aug 15, 2017

View reviewed changes

tniessen closed this Aug 16, 2017

tniessen mentioned this pull request Aug 18, 2017

doc: do not compact stability text to one line #14929

Closed

2 tasks

MylesBorins mentioned this pull request Sep 10, 2017

v8.5.0 proposal #15308

Merged

MylesBorins added the land-on-v6.x label Sep 20, 2017

MylesBorins mentioned this pull request Sep 20, 2017

v6.11.4 proposal #15506

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: fix word wrapping for api stability boxes #14809

doc: fix word wrapping for api stability boxes #14809

saadq commented Aug 13, 2017 •

edited by gibfahn

Loading

silverwind commented Aug 13, 2017 •

edited

Loading

refack commented Aug 13, 2017

silverwind commented Aug 13, 2017

refack commented Aug 13, 2017

silverwind commented Aug 13, 2017

saadq commented Aug 14, 2017 •

edited

Loading

silverwind left a comment

TimothyGu Aug 14, 2017

saadq Aug 14, 2017

saadq Aug 14, 2017 •

edited

Loading

silverwind Aug 14, 2017 •

edited

Loading

silverwind Aug 15, 2017

silverwind Aug 15, 2017

tniessen commented Aug 16, 2017

doc: fix word wrapping for api stability boxes #14809

doc: fix word wrapping for api stability boxes #14809

Conversation

saadq commented Aug 13, 2017 • edited by gibfahn Loading

Checklist

Affected core subsystem(s)

silverwind commented Aug 13, 2017 • edited Loading

refack commented Aug 13, 2017

silverwind commented Aug 13, 2017

refack commented Aug 13, 2017

silverwind commented Aug 13, 2017

saadq commented Aug 14, 2017 • edited Loading

silverwind left a comment

Choose a reason for hiding this comment

TimothyGu Aug 14, 2017

Choose a reason for hiding this comment

saadq Aug 14, 2017

Choose a reason for hiding this comment

saadq Aug 14, 2017 • edited Loading

Choose a reason for hiding this comment

silverwind Aug 14, 2017 • edited Loading

Choose a reason for hiding this comment

silverwind Aug 15, 2017

Choose a reason for hiding this comment

silverwind Aug 15, 2017

Choose a reason for hiding this comment

tniessen commented Aug 16, 2017

saadq commented Aug 13, 2017 •

edited by gibfahn

Loading

silverwind commented Aug 13, 2017 •

edited

Loading

saadq commented Aug 14, 2017 •

edited

Loading

saadq Aug 14, 2017 •

edited

Loading

silverwind Aug 14, 2017 •

edited

Loading