Opened 16 years ago

Closed 16 years ago

#1887 defect closed fixed (fixed)

Trial man page is extremely out of date

Reported by: Jonathan Lange Owned by:
Priority: high Milestone:
Component: trial Keywords: documentation
Cc: Branch:
Author:

Description

It hasn't been updated since before slyphon rewrote Trial

Change History (10)

comment:1 Changed 16 years ago by Jonathan Lange

Keywords: documentation added

comment:2 Changed 16 years ago by Jonathan Lange

Priority: normalhigh

comment:3 Changed 16 years ago by Jonathan Lange

Status: newassigned

comment:4 Changed 16 years ago by Jonathan Lange

Keywords: review added
Owner: Jonathan Lange deleted
Status: assignednew

comment:5 Changed 16 years ago by Stephen Thorne

Some things that need to be straightened out:

  • The SYNOPSIS is very rough, we probably want [OPTIONS] or something there instead of a random smattering of available options.
  • Make it clear that you have to specify what to test, and that it's not optional. The usage line in trial --help looks like trial [options] [[file|package|module|TestCase|testmethod]...] and is probably a good model.
  • The options should really be in alphabetical order.
  • The warning on --temp-directory isn't clear enough. it should really be *danger* because there's a tempation to do trial --temp-directory=/tmp instead of /tmp/mytrial/

There are options such as --supresswarnings that are omitted. Is this intentional (do I have an old version of trial?)

comment:6 Changed 16 years ago by Jonathan Lange

Owner: set to Stephen Thorne

Changes implemented.

--suppresswarnings is omitted because a) it's a noop and b) there is a branch pending review which removes the option entirely.

comment:7 Changed 16 years ago by Stephen Thorne

Keywords: review removed

Excellent. I have not tested that when you install or package twisted that this file will be installed to the correct place. Please test whatever process is in place for dealing with installing man pages, and assert that 'man trial' works as expected (I have been reading this docu using nroff -man trial.1|less)

Things that I suggest you consider adding (these are optional, and not a blocker to merging) are a url to the documentation on how to write trial tests, and an 'EXAMPLE USAGE' section.

If you do make further alterations, pop it back to me for review, otherwise please merge.

comment:8 Changed 16 years ago by Jonathan Lange

The processes for installing man pages are two-fold:

  1. Lore turns them into TeX and HTML
  2. Our Debian and RPM packages install them

Both aspects appear to work.

comment:9 Changed 16 years ago by Jonathan Lange

Resolution: fixed
Status: newclosed

(In [17493]) Update trial manpage to reflect changes since Jan 2003

  • Author: jml
  • Reviewer: Jerub
  • Fixes #1887

Trial has been changed a lot since 2003. This documents the changes in usage, adds some warnings and updates the copyright message.

comment:10 Changed 11 years ago by <automation>

Owner: Stephen Thorne deleted
Note: See TracTickets for help on using tickets.