Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: update synopsis, toc, other nits #6167

Merged
merged 3 commits into from
Apr 29, 2016
Merged

doc: update synopsis, toc, other nits #6167

merged 3 commits into from
Apr 29, 2016

Conversation

Fishrock123
Copy link
Contributor

@Fishrock123 Fishrock123 commented Apr 12, 2016 •
edited
Loading

Checklist
  • tests and code linting passes
  • documentation is changed or added
  • the commit message follows commit guidelines
Affected core subsystem(s)

doc

Description of change

There are a few things here:

  • Updated the Example to be more modern and better reflect the example in https://nodejs.org/en/about/
  • Renamed Synopsis to Usage & Example
  • Node.js(1) in the TOC is now Node.js since the former does not make sense in any context
  • The TOC is now subdivided: general about, subsystems, extra links
  • Added a toc / sidebar link to the repo/issue tracker and also the mailing list

cc @nodejs/documentation

@Fishrock123 Fishrock123 added the doc Issues and PRs related to the documentations. label Apr 12, 2016
@Fishrock123 Fishrock123 changed the title Modernize docs doc: update synopsis, toc, other nits Apr 12, 2016
@jasnell
Copy link
Member

jasnell commented Apr 12, 2016

LGTM

@Fishrock123
Copy link
Contributor Author

Here's some rendering of the toc subdivisions, tested on chrome, ff, safari:

screen shot 2016-04-12 at 1 28 30 pm

screen shot 2016-04-12 at 1 28 37 pm

@Fishrock123
Copy link
Contributor Author

Hmm, looks like I wasn't quite accurate with those shots. The lines do have the same relative margin on both sides in the sidebar.

@Knighton910
Copy link

👍

benjamingr
benjamingr reviewed Apr 12, 2016
View reviewed changes
doc/api/_toc.markdown
@@ -1,7 +1,10 @@
@// NB(chrisdickinson): if you move this file, be sure to update tools/doc/html.js to
@// point at the new location.
* [About these Docs](documentation.html)
* [Synopsis](synopsis.html)
* [Synopsis & Example](synopsis.html)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure about that

  • That file is not a synopsis of anything.
  • Example doesn't really describe much.

What about "Hello World" or "Usage" or something like that?

@benjamingr
Copy link
Member

Two nits, generally LGTM

trevnorris
trevnorris reviewed Apr 12, 2016
View reviewed changes
doc/template.html
@@ -13,7 +13,7 @@
<div id="column2" class="interior">
<div id="intro" class="interior">
<a href="/" title="Go back to the home page">
Node.js (1)
Node.js
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be more appropriate to be NODE(1).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nm. wasn't paying attention to what file this was located in. our man page should be NODE(1), but this looks good.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Our man page is NODE(1) since I rewrote it. :P

@Fishrock123
Copy link
Contributor Author

@benjamingr Updated, ptal.

@bengl have time to take a look?

@Fishrock123
Copy link
Contributor Author

As a note, I didn't rename the filename for synopsis.markdown since I didn't really want to bikeshed it here, but perhaps intro is a better name for the file.

bengl
bengl reviewed Apr 15, 2016
View reviewed changes
doc/api/synopsis.markdown
@@ -1,29 +1,43 @@
# Synopsis
# Usage
Copy link
Member

@bengl bengl Apr 15, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The title being different from the filename is potentially concerning, as mentioned already in a comment.

Could the filename be changed, and then a redirect added in synopsis.html to preserve links?

@Fishrock123
Copy link
Contributor Author

@nodejs/documentation could we get some more opinions here about the file name/title thing?

@Fishrock123
Copy link
Contributor Author

Also, if we can leave that for a later PR, that would be great; I'd really like to get some of this merged.

eljefedelrodeodeljefe
eljefedelrodeodeljefe reviewed Apr 27, 2016
View reviewed changes
doc/api/synopsis.md
Please see the [Command Line Options][] document for information about
different options and ways to run scripts with Node.

## Hello World Example
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer Hello World or "Hello World!" or nothing at all.

@eljefedelrodeodeljefe
Copy link
Contributor

LGTM w/ nits.

@Fishrock123
Copy link
Contributor Author

Updated, ## Hello World Example is now just ## Example.

@eljefedelrodeodeljefe
Copy link
Contributor

👍 done deal then.

@kahwee
Copy link

kahwee commented Apr 27, 2016

LGTM

jasnell
jasnell reviewed Apr 29, 2016
View reviewed changes
doc/api/synopsis.md
```

To run the server, put the code into a file called `example.js` and execute
it with the node program
it with Node.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: s/Node/Node.js

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe better as node example.js?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that works too

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nvm, that's on the lines below

@Fishrock123
doc: better example & synopsis
2595a7c 
nodejs#6167
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
@Fishrock123
doc: no Node.js(1)
3a4224d 
Node.js(1) does not make sense.
Node(1) would, but this isn’t a `man` page.

nodejs#6167
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
@MylesBorins
Copy link
Contributor

looks like this relies on some changes not in v4.x

@Fishrock123 please feel free to send a pr if you want to backport this

@Fishrock123
Copy link
Contributor Author

@thealphanerd This lands cleanly for me on v4.x-staging.

MylesBorins pushed a commit that referenced this pull request Jun 2, 2016
@Fishrock123
doc: better example & synopsis
a4888b0 
PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
MylesBorins pushed a commit that referenced this pull request Jun 2, 2016
@Fishrock123
doc: no Node.js(1)
fb14bc9 
Node.js(1) does not make sense.
Node(1) would, but this isn’t a `man` page.

PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
MylesBorins pushed a commit that referenced this pull request Jun 2, 2016
@Fishrock123
doc: subdivide TOC, add auxiliary links
3001f88 
PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
@MylesBorins
Copy link
Contributor

@Fishrock123 must have caught the missing bits in other backports yesterday. thanks for checking

MylesBorins pushed a commit that referenced this pull request Jun 2, 2016
@Fishrock123
doc: better example & synopsis
37daa32 
PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
MylesBorins pushed a commit that referenced this pull request Jun 2, 2016
@Fishrock123
doc: no Node.js(1)
124dfc1 
Node.js(1) does not make sense.
Node(1) would, but this isn’t a `man` page.

PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
MylesBorins pushed a commit that referenced this pull request Jun 2, 2016
@Fishrock123
doc: subdivide TOC, add auxiliary links
a87269d 
PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
@MylesBorins MylesBorins mentioned this pull request Jun 24, 2016
Merged
MylesBorins pushed a commit that referenced this pull request Jun 24, 2016
@Fishrock123
doc: better example & synopsis
401325f 
PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
MylesBorins pushed a commit that referenced this pull request Jun 24, 2016
@Fishrock123
doc: no Node.js(1)
107839c 
Node.js(1) does not make sense.
Node(1) would, but this isn’t a `man` page.

PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
MylesBorins pushed a commit that referenced this pull request Jun 24, 2016
@Fishrock123
doc: subdivide TOC, add auxiliary links
eadb7e5 
PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
MylesBorins pushed a commit that referenced this pull request Jun 24, 2016
@Fishrock123
doc: better example & synopsis
d3c7b58 
PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
MylesBorins pushed a commit that referenced this pull request Jun 24, 2016
@Fishrock123
doc: no Node.js(1)
f7068d4 
Node.js(1) does not make sense.
Node(1) would, but this isn’t a `man` page.

PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
MylesBorins pushed a commit that referenced this pull request Jun 24, 2016
@Fishrock123
doc: subdivide TOC, add auxiliary links
3189446 
PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
doc Issues and PRs related to the documentations.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
9 participants
@Fishrock123 @jasnell @Knighton910 @benjamingr @eljefedelrodeodeljefe @kahwee @MylesBorins @bengl @trevnorris