Opened 9 years ago

Closed 8 years ago

#3246 task closed fixed (fixed)

remove all mentions of plugins.tml from the documentation

Reported by: radix Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: thijs Branch: branches/remove-plugins-tml-3246-2
branch-diff, diff-cov, branch-cov, buildbot
Author: thijs, exarkun

Description

There are a couple mentions in The Tutorial, and one in the TwistedQuotes document:

./howto/quotes.xhtml:    <li><a href="listings/TwistedQuotes/plugins.tml" class="py-listing">plugins.tml</a>.</li>
./howto/tutorial/configuration.xhtml:<a href="listings/finger/finger/plugins.tml" class="py-listing">finger/plugins.tml</a>
./howto/tutorial/listings/finger/finger/plugins.tml:#finger/plugins.tml

Change History (22)

comment:1 Changed 9 years ago by radix

There's also a few in the lore documentation.

comment:2 Changed 8 years ago by collab

  • Cc collab added
  • Keywords documentation added

comment:3 Changed 8 years ago by collab

  • Owner changed from glyph to collab
  • Status changed from new to assigned

comment:4 Changed 8 years ago by thijs

  • Cc thijs added; collab removed
  • Owner changed from collab to thijs
  • Status changed from assigned to new

comment:5 Changed 8 years ago by thijs

  • author set to thijs
  • Branch set to branches/remove-plugins-tml-3246

(In [24528]) Branching to 'remove-plugins-tml-3246'

comment:6 Changed 8 years ago by thijs

  • Status changed from new to assigned

I assume the task here is to rewrite the .tml examples/documentation and convert them to the new plugin system as described on this page.

comment:7 Changed 8 years ago by thijs

  • Keywords review added
  • Owner thijs deleted
  • Status changed from assigned to new

I'm not very familiar with the plugins system in Twisted but read the docs and attempted to move the TwistedQuotes app to the twisted.plugin.IPlugin approach. The TwistedQuotes page doesn't describe how to actually run the sample without the use of mktap, if I understand correctly, so if someone can let me know if I'm 1) on the right path with the plugin approach in r24530 and 2) what the preferred approach of running a plugin with twistd/.tac's is.

comment:8 follow-up: Changed 8 years ago by radix

  • Keywords review removed
  • Owner set to thijs

Ok, so I don't think that TwistedQuotes should have plugins at all. None of the documents that refer to it actually talk about plugins (except for a misuse in design.xhtml, which refers to TwistedQuotes itself as a "plugin" but should instead use the word "package"). For example, none of the documents actually explain what that 'plugins.tml' file was doing in the TwistedQuotes package; they were probably removed a while ago.

I think we already have a good enough example of plugins in the plugins document itself, and including plugins support in TwistedQuotes is likely to just confuse readers.

So I think you should just get rid of the plugins.tml file, get rid of the reference to it in quotes.xhtml, and update design.xhtml to refer to TwistedQuotes as a "package" instead of a "plugin".

Sorry for the long review period, thijs.

comment:9 in reply to: ↑ 8 Changed 8 years ago by thijs

  • Keywords review added
  • Owner thijs deleted

Replying to radix:

So I think you should just get rid of the plugins.tml file, get rid of the reference to it in quotes.xhtml, and update design.xhtml to refer to TwistedQuotes as a "package" instead of a "plugin".

Made the suggested changes in r24620, putting it up for review.

comment:10 follow-up: Changed 8 years ago by exarkun

  • Keywords review removed
  • Owner set to thijs
  1. doc/core/howto/listings/TwistedQuotes/quoteproto.py only has whitespace changes, and they look like they change the code to not conform to the coding standard.
  2. Ditto for doc/core/howto/listings/TwistedQuotes/quoters.py
  3. There are some more mentions of plugins.tml:
    • doc/lore/howto/extend-lore.xhtml
    • doc/lore/howto/listings/lore/plugins.tml
    • doc/core/howto/tutorial/configuration.xhtml
    • doc/core/howto/tutorial/listings/finger/finger/plugins.tml

Let me know if you'd still like an answer to the questions you asked in your comment prior to radix's review.

comment:11 in reply to: ↑ 10 Changed 8 years ago by thijs

  • Keywords review added
  • Owner thijs deleted

Replying to exarkun:

  1. doc/core/howto/listings/TwistedQuotes/quoteproto.py only has whitespace changes, and they look like they change the code to not conform to the coding standard.
  2. Ditto for doc/core/howto/listings/TwistedQuotes/quoters.py

Right, reverted that change in r24641

  1. There are some more mentions of plugins.tml:
    • doc/lore/howto/extend-lore.xhtml
    • doc/lore/howto/listings/lore/plugins.tml

I can't just rip this lore example out without influencing the rest of the howto, or..? What to do with this?

  • doc/core/howto/tutorial/configuration.xhtml
  • doc/core/howto/tutorial/listings/finger/finger/plugins.tml

Should this tml/mktap stuff be replaced by a .tac?

comment:12 Changed 8 years ago by exarkun

  • Keywords review removed
  • Owner set to thijs

I can't just rip this lore example out without influencing the rest of the howto, or..? What to do with this?

Lore supports new-style plugins too, so I think the change we need to make is to convert the .tml file to a new-style plugin and update the prose which talks about it to agree. Hopefully a lot of text will be obsolete or can be replaced with a reference to the plugin howto.

Should this tml/mktap stuff be replaced by a .tac?

A twistd plugin probably makes more sense and is a smaller change. All mktap plugins are twistd plugins by default. So this would become like "twistd finger ..." instead of "mktap finger ...; twistd -f finger.tap".

comment:13 Changed 8 years ago by exarkun

(In [25643]) replace the old-style lore plugin with a new-style lore plugin and update the documentation

refs #3246

comment:14 Changed 8 years ago by exarkun

(In [25644]) replace the old-style finger plugin with a new-style twistd plugin and update the documentation

refs #3246

comment:15 Changed 8 years ago by exarkun

(In [25645]) stop talking about TwistedQuotes entirely

The plugin stuff is all irrelevant to this pb document. The features relevant to pb explained by TwistedQuotes are already explained in other parts of this document.

refs #3246

comment:16 Changed 8 years ago by exarkun

(In [25646]) get rid of another TwistedQuotes tml file

refs #3246

comment:17 Changed 8 years ago by exarkun

  • Author changed from thijs to thijs, exarkun
  • Branch changed from branches/remove-plugins-tml-3246 to branches/remove-plugins-tml-3246-2

(In [25647]) Branching to 'remove-plugins-tml-3246-2'

comment:18 Changed 8 years ago by exarkun

  • Keywords review added
  • Owner thijs deleted

Fixed the remaining issues, I think. Please review.

comment:19 Changed 8 years ago by thijs

  • Keywords review removed
  • Owner set to exarkun

Looks good to me, not sure why you're commenting out some stuff in extend-lore.xhtml though?

comment:20 Changed 8 years ago by exarkun

I commented out the stuff in lore because it wasn't providing any value to readers. It might be useful to a future lore maintainer as a hint about what documentation still needs to be written, though.

comment:21 Changed 8 years ago by exarkun

  • Resolution set to fixed
  • Status changed from new to closed

(In [25672]) Merge remove-plugins-tml-3246-2

Author: thijs, exarkun, itamarst Reviewer: radix, thijs Fixes: #3246

Remove from the documentation all remaining references to the old style of plugins and replace them with documentation based on the new style of plugins, where appropriate. The Lore plugin interface IProcess is also slightly improved so that it at least defines the attributes which are actually required of it and does not document an attribute which is never used by Lore.

comment:22 Changed 6 years ago by <automation>

  • Owner exarkun deleted
Note: See TracTickets for help on using tickets.