Opened 5 years ago

Closed 4 years ago

#6476 task closed wontfix (wontfix)

SMTP client howto contains outdated example output

Reported by: Thijs Triemstra Owned by:
Priority: low Milestone:
Component: mail Keywords: documentation easy
Cc: Thijs Triemstra Branch:
Author:

Description

[source:trunk/doc/mail/tutorial/smtpclient/smtpclient.xhtml] contains a lot of output from the various examples used in the howto, like:

19:10 EST [-] twistd SVN-Trunk (/usr/bin/python2.4 2.4.1) starting up
19:10 EST [-] reactor class: twisted.internet.selectreactor.SelectReactor
19:10 EST [-] Loading smtpclient-3.tac...
19:10 EST [-] Loaded.

First of all the timestamp is wrong, nowadays i see a full date/time (but perhaps this was done to keep the output as minimal as possible, but this should be updated imo). The title of the twistd command has changed. The default reactor class is epoll, and the tac loading message is also gone nowadays.

The person resolving this ticket should go through all the examples and update the output for each example.

Change History (1)

comment:1 Changed 4 years ago by Jean-Paul Calderone

Resolution: wontfix
Status: newclosed

Thanks for your attention to detail here, however I think this is not actually a task w eshould take on or encourage others to take on.

Minor details, such as the exact formatting of log timestamps, are going to continue to change forever. Other things, like the reactor which gets used, already vary from platform to platform - so the output *cannot* be correct for everyone. And as an extreme example, the version of Twisted changes from release to release.

Output that is literally included in a howto is always going to be slightly different from the output a reader who tries to reproduce it can produce. If this is somehow a bad thing, then the approach to writing documentation needs to change at a much more basic level. The solution is not to spend dozens of hours every release manually tweaking this static information.

By all means, make changes that are important to actual understanding of the APIs the tutorial is trying to explain. But none of the differences highlighted here are worth it.

Or, add some explanation to the prose so that if a reader has an expectation of byte for byte exact output, it is dispelled.

Or propose some completely different way to write this documentation that doesn't involve byte for byte exact output that ends up getting desynchronized with real results.

Note: See TracTickets for help on using tickets.