Opened 8 years ago

Closed 7 years ago

#4239 defect closed fixed (fixed)

Several "orphaned" pages in Lore format documentation

Reported by: khorn Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: Thijs Triemstra, jesstess Branch: branches/orphaned-pages-4239
branch-diff, diff-cov, branch-cov, buildbot
Author: khorn

Description

The following pages exist in the Twisted documentation, but nothing links to them. They are not listed in any index pages, and do not appear to be linked from any other pages either.

/web/howto/formindepth.xhtml
/core/howto/pclients.xhtml
/core/howto/upgrading.xhtml
/pair/examples/index.xhtml

Change History (17)

comment:1 Changed 8 years ago by khorn

/web/howto/formindepth.xhtml - Just contains "XXX: to be written", so it probably should be. It would be helpful to know what this document was intended to cover...

/core/howto/pclients.xhtml - Has content, but just isn't linked to for some unknown reason. Also, perhaps this should be renamed "pb-clients" or something similar, to follow the pattern of the other Perspective Broker docs?

/core/howto/upgrading.xhtml - Appears to be all about "versioned" PB applications. Perhaps it also needs to be renamed?

/pair/examples/index.xhtml - This just looks like a missing link. Shouldbe an easy fix.

comment:2 Changed 8 years ago by Thijs Triemstra

Cc: Thijs Triemstra added

Can you branch for this so we can test with the doc build slave?

comment:3 Changed 8 years ago by khorn

Apparently mkbranch from Combinator doesn't work on Windows at all, and that's what I have working right now. So I can't make branches from Combinator. Either someone else can create the branch, or I can create one using SVN, but I'm not clear on whether mkbranch just creates the branch normally or if it does something special with respect to Combinator.

Please advise...

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

Making a branch without Combinator just involves the usual svn stuff. The only thing to pay attention to is that you should copy trunk in a different revision from applying any changes to it.

comment:5 Changed 8 years ago by khorn

Author: khorn
Branch: branches/orphaned-pages-4239

(In [28168]) Branching to 'orphaned-pages-4239'

comment:6 Changed 7 years ago by khorn

Keywords: review added
Owner: khorn deleted

proposed changes in [28717]

sending to review...

comment:7 Changed 7 years ago by jesstess

Owner: set to jesstess

comment:8 Changed 7 years ago by jesstess

Cc: jesstess added
Keywords: review removed
Owner: changed from jesstess to khorn
  • Nothing in twisted/pair/* has a copyright above 2004, and running the pairudp.py example given a link in the pair examples index in this branches gets me ImportError: No module named eunuchs.tuntap. If pairudp.py is going to be linked, it should probably have a shebang line and a copyright like other examples. Whether or not this example should even still exist probably needs perspective from someone who knows if Pair is theoretically maintained still (aka not me).
  • "Miscellaneous" is spelled incorrectly on the pair index.xhtml
  • updated.xhtml and pb-client.xhtml talk about things that aren't deprecated and have even been updated recently in some cases, so it seems plausible that they really should be linked from the howto. Both have trailing whitespace. I didn't do a full documentation check on them because that would blow up changes on this ticket. If you're interested, file another another one for markup issues in these files and consider linking good enough.

comment:9 Changed 7 years ago by jesstess

Formatting fail:

  • Nothing in twisted/pair/* has a copyright above 2004, and running the pairudp.py example given a link in the pair examples index in this branches gets me ImportError: No module named eunuchs.tuntap. If pairudp.py is going to be linked, it should probably have a shebang line and a copyright like other examples. Whether or not this example should even still exist probably needs perspective from someone who knows if Pair is theoretically maintained still (aka not me).
  • "Miscellaneous" is spelled incorrectly on the pair index.xhtml
  • updated.xhtml and pb-client.xhtml talk about things that aren't deprecated and have even been updated recently in some cases, so it seems plausible that they really should be linked from the howto. Both have trailing whitespace. I didn't do a full documentation check on them because that would blow up changes on this ticket. If you're interested, file another another one for markup issues in these files and consider linking good enough.

comment:10 Changed 7 years ago by jesstess

Also formindepth.xhtml from the ticket summary isn't currently addressed (deleted?) in the branch.

comment:11 Changed 7 years ago by khorn

actually I left formindepth.xhtml alone...since it's effectively empty and I had no idea what it was intended to be.

I meant to note that here in the ticket, but apparently forgot.

comment:12 Changed 7 years ago by khorn

(In [28753]) Address review comments

  • remove training whitespace
  • spelling fix

Refs: #4239

comment:13 Changed 7 years ago by khorn

Keywords: review added
Owner: khorn deleted

comment:14 Changed 7 years ago by jesstess

Keywords: review removed
Owner: set to khorn

Thanks for pushing through these documentation improvements, khorn.

  • If pairudp.py is going to stay linked, it needs a shebang line and a copyright like other examples, and a ticket to get it working.
  • I think formindepth.xhtml should just be deleted. I don't see any tickets related to completing it.

I see now that TwistedProjects lists Twisted Pair as unmaintained. We need to get someone to admit the true state of Twisted Pair on IRC or the mailing list so we can work on removing it if that's what needs to happen.

Other than that, looks good to merge!

comment:15 Changed 7 years ago by khorn

(In [28761]) Address further review comments

  • remove /doc/web/howto/formindepth.xhtml
  • add copyright header to /doc/pair/examples/pairudp.py

Refs: #4239

comment:16 Changed 7 years ago by khorn

Resolution: fixed
Status: newclosed

(In [28766]) Fix links for orphaned pages in docs

  • remove doc/web/howto/formindepth.xhtml
  • rename doc/core/howto/pclients.xhtml (to pb-clients.xhtml)
  • add copyright header and shebang line to pair/examples/pairudp.py
  • added some links to point to orphaned pages

Author: khorn Reviewer: jesstess Fixes: #4239

comment:17 Changed 7 years ago by <automation>

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