Twisted overview graph shows Xish

[ralphm]

The graphical overview at  http://twistedmatrix.com/projects/core/documentation/howto/overview.html still shows Xish as a separate component. However, it has been folder into Words a while back.

[exarkun]

It also shows Twisted.Flow, Twisted.Protocols as containing all the protocol implementations, half the executables in the wrong place, and implies "String ports" is a fundamental part of core twisted. Basically half this picture is wrong. The whole thing needs a going over.

[ralphm]

Would 2.3 be a good target for this?

[thijs]

Replying to exarkun:

Basically half this picture is wrong. The whole thing needs a going over.

Are the source files for those diagrams available?

[exarkun]

There's doc/core/img/twisted-overview.dia, that's probably it.

[thijs]

(In [25338]) Branching to 'overview-graph-1712'

[thijs]

Removed xish and flow from the diagram in r25339, I'll need a better description/suggestion to restructure the diagram. Putting it up for review.

[ralphm]

Your change indeed fixes the problem described in this ticket. Is your question whether this diagram should have more changes? I think so. Should it go into this ticket? I'd agree on widening the scope of this ticket.

[exarkun]

Yes. The diagram still needs a lot of work. Even with xish in the right place now, it doesn't really convey useful information to someone trying to learn about Twisted. It's just a bunch of boxes and words and arrows.

We could remove it entirely or someone who's familiar with the various abstractions in Twisted could try fixing it (perhaps by starting over from scratch) to be useful.

A couple other specific problems with the current form:

• it includes mktap, which we've stopped documenting anywhere else
• it talks about bin/lore instead of bin/lore/lore

There are doubtless other issues, but those are the two which I noticed first. Even if these are fixed, the diagram is still not useful (but the problems shouldn't be replicated in any future version).

As a roughly orthogonal issue, dia doesn't seem like the best format we could use for this kind of thing. I'd suggest svg for a future version (but whatever).

Speculatively reassigning this to someone who might fall into the familiar with the various abstractions in Twisted group.

[thijs]

Assigning to radix for review then.

[radix]

I'm not sure what I'm supposed to be reviewing here. It looks like this ticket is in need of implementation before I can review it.

[thijs]

Let's include exarkun's suggestions and then hopefully merge:

• it includes mktap, which we've stopped documenting anywhere else
• it talks about bin/lore instead of bin/lore/lore

[exarkun]

Other things that are wrong with the diagram:

1. twisted.protocols no longer contains any of the protocols it talks about (except telnet, which is deprecated). Instead it should actually be listing at least some of the stuff (ftp and socks, anyway) from the "Other" box in the "Twisted.Servers" section.
2. "Twisted.Servers"? What does that mean? Those look like more "Twisted Subprojects", except for "Other", which I think we should just drop.

[thijs]

I suggest we redo it in .svg so it can be opened in other programs besides Dia, which doesn't allow me to edit the text in the trunk's file.