Opened 16 years ago

Closed 13 years ago

#1888 task closed fixed (fixed)

Review man pages

Reported by: Jonathan Lange Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: teratorn, Thijs Triemstra Branch: branches/review-man-pages-1888
branch-diff, diff-cov, branch-cov, buildbot
Author: thijs

Description

Does anyone actually update manpages?

Attachments (1)

man-1888.patch (8.9 KB) - added by collab 14 years ago.
patch against r24237

Download all attachments as: .zip

Change History (17)

comment:1 Changed 16 years ago by Jonathan Lange

Cc: teratorn added

comment:2 Changed 14 years ago by collab

Cc: collab added

comment:3 Changed 14 years ago by collab

Owner: changed from edsuom to collab
Status: newassigned

I'll start with the most used tools (twistd, trial etc).

Changed 14 years ago by collab

Attachment: man-1888.patch added

patch against r24237

comment:4 Changed 14 years ago by collab

Keywords: review added
Owner: collab deleted
Status: assignednew

Reviewed the man pages, see attached patch.

comment:5 Changed 14 years ago by Thijs Triemstra

Cc: Thijs Triemstra added; collab removed

comment:6 Changed 14 years ago by Jean-Paul Calderone

Keywords: review removed
Owner: set to Thijs Triemstra
  • No one really uses the --extra parameter to trial anymore. The option should probably be deprecated, then removed. Documenting it is okay, but doesn't really add much.
  • The --euid option to twistd also sets the egid instead of the gid. Also, it does shed privileges, it just does so with seteuid and setegid instead of setuid and setgid. I think it's a bit misleading to document it as it is documented in this patch.
  • In the conch man page, received is misspelled as receieved.

Please check the patch into a branch and force a build of it on the documentation builder to make sure everything parses/etc.

comment:7 in reply to:  6 Changed 14 years ago by Thijs Triemstra

Branch: branches/review-man-pages-1888
Status: newassigned

Replying to exarkun:

No one really uses the --extra parameter to trial anymore. The option should probably be deprecated, then removed. Documenting it is okay, but doesn't really add much.

ok, left it in the branch.

The --euid option to twistd also sets the egid instead of the gid. Also, it does shed privileges, it just does so with seteuid and setegid instead of setuid and setgid. I think it's a bit misleading to document it as it is documented in this patch.

Shall I leave out the --euid option?

In the conch man page, received is misspelled as receieved.

Please check the patch into a branch and force a build of it on the documentation builder to make sure everything parses/etc.

Created a new [source:branches/review-man-pages-1888 branch].

comment:8 Changed 14 years ago by Thijs Triemstra

author: thijs

(In [24429]) Branching to 'review-man-pages-1888'

comment:9 in reply to:  6 Changed 14 years ago by Thijs Triemstra

Keywords: review added
Owner: Thijs Triemstra deleted
Status: assignednew

Replying to exarkun:

Please check the patch into a branch and force a build of it on the documentation builder to make sure everything parses/etc.

Created a new branch and the doc builder reports now problems: http://buildbot.twistedmatrix.com/builders/documentation/builds/711

Putting it up for review.

comment:10 Changed 14 years ago by Jean-Paul Calderone

Keywords: review removed
Owner: set to Thijs Triemstra

I'd include --euid, but document it more precisely than it was in the patch.

The rest of the changes look just fine.

comment:11 in reply to:  10 Changed 14 years ago by Thijs Triemstra

Replying to exarkun:

I'd include --euid, but document it more precisely than it was in the patch.

I tried to put your description of euid in there but I can't come up with anything that makes sense, cause I'm not familiar with the technical details behind it. If you can give me a good description I'd be happy to merge it in there.

comment:12 Changed 14 years ago by Thijs Triemstra

Status: newassigned

fyi: I included the original description from the patch in the branch (r24469).

comment:13 Changed 13 years ago by Thijs Triemstra

Keywords: review added
Owner: changed from Thijs Triemstra to Jean-Paul Calderone
Status: assignednew

comment:14 Changed 13 years ago by Jean-Paul Calderone

Keywords: review removed
Owner: changed from Jean-Paul Calderone to Thijs Triemstra

On second thought, the man page now matches the output of twistd --help. Maybe euid documentation should be improved too, but this ticket is just about updating the man pages.

So, looks good to me, please merge.

comment:15 Changed 13 years ago by Thijs Triemstra

Resolution: fixed
Status: newclosed

(In [24568]) Merge review-man-pages-1888: Reviewed man pages for commandline tools

Author: thijs Reviewer: exarkun Fixes: #1888

comment:16 Changed 11 years ago by <automation>

Owner: Thijs Triemstra deleted
Note: See TracTickets for help on using tickets.