doc: make node(1) more consistent with tradition #8902

strugee · 2016-10-03T10:24:41Z

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc

Description of change

Removed loads of whitespace
Added traditional BUGS and AUTHORS sections
Renamed ENVIRONMENT VARIABLES to ENVIRONMENT, as is traditional

In particular I'm not sure if everyone will be cool with the BUGS text - I personally think it's good but if anyone disagrees I'm not super attached to it. Also, I put .\"s instead of outright removing the newlines because I think it's (slightly) more readable, but I can also get rid of those.

bnoordhuis · 2016-10-03T11:19:21Z

The "has many bugs" in the BUGS section is too nondescript to be useful, I'd change it to a REPORTING BUGS section with a link to the bug tracker.

I personally don't care for an AUTHORS section; it's not very relevant to readers and in our case it's misleading because Ryan hasn't worked on node for something like four years now.

Suggestion: a LICENSE section might be a good addition.

addaleax · 2016-10-03T11:40:57Z

doc/node.1

+.\"
+.SH AUTHORS
+Written by Ryan Dahl and maintained by 1000+ contributors:
+.ur https://github.com/nodejs/node/blog/master/AUTHORS


Should this be “blob”?

Nice catch! Fixed.

Fishrock123 · 2016-10-03T14:02:23Z

I don't agree with the ./" -- imo this will only make it harder for people less familiar to contribute to this. I suggest removing those.

Fishrock123 · 2016-10-03T14:03:10Z

doc/node.1

+.ur https://github.com/nodejs/node/issues
+.\"
+.SH AUTHORS
+Written by Ryan Dahl and maintained by 1000+ contributors:


Effectively written by many others too. I would just link to the AUTHORS.

Fishrock123 · 2016-10-03T14:03:57Z

doc/node.1

+.\"
+.SH BUGS
+Node.js has many bugs; they are tracked in GitHub Issues:
+.ur https://github.com/nodejs/node/issues


same, maybe just link the issue tracker? it's also linked below though....

imo, just remove

strugee · 2016-10-03T21:39:10Z

@bnoordhuis @Fishrock123 changed the wording of the BUGS section to be more concise. If people still disagree with this I can just remove it entirely

I also changed AUTHORS to not mention Ryan, got rid of the .\"s and added a COPYRIGHT section

Fishrock123 · 2016-10-04T14:00:25Z

doc/node.1

 .\" Macro to display an underlined URL in bold
 .de ur
 .nr CF \\n(.f
 .ft 4
 \\$1
 .ft \\n(CF
 ..
-
-


Sorry, I meant not to touch these at all.

I know it's not "perfectly syntactically correct" but it is far more readable.

In my experience the problems with rendering are negligible if any for the potential cost of people having a hard time contributing.

Fishrock123 · 2016-10-04T14:00:53Z

doc/node.1

+.SH BUGS
+Bugs are tracked in GitHub Issues:
+.ur https://github.com/nodejs/node/issues
+.SH AUTHORS


Add spaces between please (see above note)

Fishrock123 · 2016-10-04T14:01:47Z

doc/node.1

+Written and maintained by 1000+ contributors:
+.ur https://github.com/nodejs/node/blob/master/AUTHORS
+.SH COPYRIGHT
+Copyright Node.js contributors. All rights reserved. Node.js is available under the MIT license.


I don't think this correct -- all rights are not reserved, it is licensed under MIT.

Honestly, I thought so too. But that's what LICENSE says. Does that need to be changed too?

@Fishrock123 changed this despite the inconsistency with LICENSE.

Fishrock123 · 2016-10-04T14:02:11Z

doc/node.1

-
-.SH ENVIRONMENT VARIABLES
-
+.SH ENVIRONMENT


I think the previous wording is more obvious.

strugee · 2016-10-04T17:48:13Z

jasnell

Couple of nits I'd like to see fixed up but otherwise LGTM

jasnell · 2016-10-06T17:00:11Z

doc/node.1

@@ -219,5 +231,5 @@ Mailing list:
 IRC (general questions):
 .ur "chat.freenode.net #node.js"

-IRC (node core development):
+IRC (Node core development):


s/Node/Node.js

jasnell · 2016-10-06T17:01:07Z

doc/node.1

@@ -219,5 +231,5 @@ Mailing list:
 IRC (general questions):
 .ur "chat.freenode.net #node.js"


Nit: Given that #node.js is not yet considered an official resource managed by the project, a note indicating it's unofficial status might be worthwhile.

Fishrock123 · 2016-10-06T17:42:53Z

doc/node.1

+.SH BUGS
+Bugs are tracked in GitHub Issues:
+.ur https://github.com/nodejs/node/issues
+.SH AUTHORS


could please add spaces here? looks good other than that

strugee · 2016-10-06T21:04:10Z

👍 all issues fixed; this is ready to merge

jasnell · 2016-10-07T17:33:24Z

doc/node.1

+.SH COPYRIGHT
+Copyright Node.js contributors. Node.js is available under the MIT license.
+
+Node.js also includes external libraries that are available under a variety of licenses. See


nit: long line here. could be fixed when landing.

* Added traditional BUGS, AUTHORS and COPYRIGHT sections * Fixed some minor issues with the IRC links

* Added traditional BUGS, AUTHORS and COPYRIGHT sections * Fixed some minor issues with the IRC links PR-URL: #8902 Reviewed-By: Jeremiah Senkpiel <[email protected]> Reviewed-By: James M Snell <[email protected]>

jasnell · 2016-10-08T15:51:01Z

Landed in 90cd39f. Thank you!

strugee · 2016-10-08T19:05:50Z

Thanks very much! 👍

* Added traditional BUGS, AUTHORS and COPYRIGHT sections * Fixed some minor issues with the IRC links PR-URL: #8902 Reviewed-By: Jeremiah Senkpiel <[email protected]> Reviewed-By: James M Snell <[email protected]>

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Oct 3, 2016

addaleax reviewed Oct 3, 2016

View reviewed changes

Fishrock123 suggested changes Oct 3, 2016

View reviewed changes

strugee force-pushed the better-manpage branch from f02d24b to 93efcd8 Compare October 3, 2016 21:39

strugee force-pushed the better-manpage branch from 93efcd8 to a84da3f Compare October 3, 2016 21:39

Fishrock123 suggested changes Oct 4, 2016

View reviewed changes

strugee force-pushed the better-manpage branch from a84da3f to 22e5f96 Compare October 4, 2016 17:47

jasnell approved these changes Oct 6, 2016

View reviewed changes

Fishrock123 reviewed Oct 6, 2016

View reviewed changes

strugee force-pushed the better-manpage branch from 22e5f96 to deb7cd5 Compare October 6, 2016 21:02

Fishrock123 approved these changes Oct 6, 2016

View reviewed changes

jasnell reviewed Oct 7, 2016

View reviewed changes

strugee force-pushed the better-manpage branch from deb7cd5 to 1a6c407 Compare October 8, 2016 07:48

doc: make node(1) more consistent with tradition

9d477f5

* Added traditional BUGS, AUTHORS and COPYRIGHT sections * Fixed some minor issues with the IRC links

strugee force-pushed the better-manpage branch from 1a6c407 to 9d477f5 Compare October 8, 2016 07:51

jasnell closed this Oct 8, 2016

MylesBorins added the land-on-v4.x label Nov 22, 2016

MylesBorins mentioned this pull request Nov 22, 2016

v4.7.0 proposal #9736

Merged

strugee deleted the better-manpage branch August 26, 2017 22:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: make node(1) more consistent with tradition #8902

doc: make node(1) more consistent with tradition #8902

strugee commented Oct 3, 2016

bnoordhuis commented Oct 3, 2016

addaleax Oct 3, 2016

strugee Oct 3, 2016

Fishrock123 commented Oct 3, 2016

Fishrock123 Oct 3, 2016

Fishrock123 Oct 3, 2016

strugee commented Oct 3, 2016

Fishrock123 Oct 4, 2016

Fishrock123 Oct 4, 2016

Fishrock123 Oct 4, 2016

strugee Oct 4, 2016

strugee Oct 4, 2016

Fishrock123 Oct 4, 2016

strugee commented Oct 4, 2016

jasnell left a comment

jasnell Oct 6, 2016

jasnell Oct 6, 2016

Fishrock123 Oct 6, 2016

strugee commented Oct 6, 2016

jasnell Oct 7, 2016

strugee Oct 8, 2016

jasnell commented Oct 8, 2016

strugee commented Oct 8, 2016

		@@ -219,5 +231,5 @@ Mailing list:
		IRC (general questions):
		.ur "chat.freenode.net #node.js"

doc: make node(1) more consistent with tradition #8902

doc: make node(1) more consistent with tradition #8902

Conversation

strugee commented Oct 3, 2016

Checklist

Affected core subsystem(s)

Description of change

bnoordhuis commented Oct 3, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Fishrock123 commented Oct 3, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

strugee commented Oct 3, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

strugee commented Oct 4, 2016

jasnell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

strugee commented Oct 6, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Oct 8, 2016

strugee commented Oct 8, 2016