Feature completed, committed to documentation: TWiki06x01.ManagingTopics

---

Visitors often create imprecise or inappropriate TWiki topic names. Just as other visitors are free to ammend, append, or just plain delete the content of a topic, they should also be able to change the name of the topic.

After clicking the Rename Topic link, the user would be presented with a form where they would enter a new name for the topic, and choose one of: * Replace all references to OldTopicName with references to this new name * Leave all references to OldTopicName unchanged

(probably defaulting to the first) The user would then "submit" the form to rename the topic.

-- PaulReiber - 02 Jan 2001

---

Don't forget to rename the sub directory pub/webname/topicname with the attached files.

-- StefanScherer - 05 Jan 2001

---

My users want RenameTopic with replacin all references, but how do you resolve locking conflicts? My only idea is to come up with an intermediate page that lists all reffering pages with tickboxes for all the pages on which to replace, and to very visibly disable the pages that are locked.. Yuck -- SvenDowideit - 09 Jan 2001

The attached source could be triggered from a utility page, but there is no lock checking...

-- SvenDowideit - 16 Jan 2001

rename.pl looks good, on the locking, are you going to update to do something like: * Give list of topics to change, mark if they can be done automatically (not locked) * User gives go ahead * List pages that were not done automatically * A fancy option (probably too fancy) would be to remember the updates that could not be done and keep trying every x minutes.

Will rename go in wikistore and deal with templates, RCS etc as well as topic file?

-- JohnTalintyre - 16 Jan 2001

Yep, yep and yep , but its taking time, I just looked at it again for the first time since i uploaded, and I think that I will simply make a rename.tmpl that will list all the things that are about to be done (and a list of those that can't) and the user can give the go-ahead (again and again and again until they are bored, or all the reffering pages are done)

I had an idea about the re-try, it is possible to record the 'failed' renames and for them to be done when a user previews the page that they are editing.. that would mean no x minutes, just do it when there are no clashes..

This solution could be similar to merging two simultanious changes maybe.. -- SvenDowideit - 28 Jan 2001

I have done some more work on this - I changed the interface to use a Rename topic that has an embedded SEARCH to show what pages would be modified. it also now renames the attached files directory, and updates wikistore (kind of - its hard coded to use vss at the moment). The last thing to add will be contention handeling... To simplify page selection I created a simple way to SetTemporaryValues..

-- SvenDowideit - 10 Feb 2001

I have tried the code ... perhaps there is a bug ... the script renames also partial names (e.g. if I rename "FooBar" -> "FooBaz" I find FooBarBaz changed to FooBazBaz)

-- AndreaSterbini - 11 Feb 2001

yep, that would be a huge bug fixed (badly)

-- SD

I think the main reason why renaming is so difficult is because RCS cannot handle this. AFAIK the CVS community has been thinking about the problem for months if not years now, and I still hear nothing, so it's probably incompatible with the way RCS works. (Anybody with more precise information is welcome to correct this!)

For me, this sums up to the fact that rolling back renames will always run into some problem, sooner or later.

I see two reasonable solutions here:

1. Replace RCS with a tool that can handle file renames, such as Aegis (see http://www.canb.auug.org.au/~millerp/aegis/aegis.html).
2. Do not rely on file names for topic names. Store the topic name in the first line of a topic file instead.

(1) may be a bit difficult to implement. Tools that take file name changes into account must consider every change as global, so if we want to roll back the changes in just one file we'll have to make sure that all changes in other topics are reapplied (which has the potential for conflicts).

(2) is easy to implement: you never rename files, you just change the first line, and otherwise let RCS do all the magic for you.
Other topics may still carry the old name, but the link will still work; TWiki can update such stale links whenever appropriate (e.g. when the topic is called up, at which time the file must be parsed and converted anyway).
There is one substantial change within TWiki itself: the text files must now carry both the topic name and the file name for a link, so it's not just scanning for Wiki Words anymore, it needs "real syntax" now. (This need not affect input. The edit function can still pick up Wiki Words and generate topic links from them. Or the scanner handles both old-style Wiki Words and new-fangled topic-plus-file-name links and converts them into HTML links. And that "real syntax" could still look very simple, like WikiWordAfterRenaming:OriginalTopicName .)

(I know I should implement this myself, but I have too many other things waiting in the queue, so anybody who'd like to explore this further is invited to pick the lead up and carry it to completion.)

-- JoachimDurchholz - 26 Mar 2001

---

Another feature that I would like to add is ShowLockStatusInSearch. I am have added a new option showlock to the embedded search, which shows if the rename cannot rename a link in a page..

If there is a page Locked, the script will do what it can, and go back to the RenamePage topic (with the REDO flag set) The user can then redo til they're bored.

---

If you just want a simple shell script to rename a topic, here's one: renameTopic.sh

See also MoveTopic.

-- AndrewFuqua - 16 Feb 2001

????? the .lock file is there to tell you that someone is modifying the topic... therefoe after you mv the files that person is effectively creating a new page with the old name.. There needs to be interaction with the user..

-- SvenDowideit - 18 Feb 2001

---

I've taken the rename script and done some work with it. Work in progress attached. What I've done:

• moved most of rename function to wikistore.pm
  • also deal with attachment under revision control
  • See AttachmentsUnderRevisionControl
• changed search so that it lists other topics to be changed
  • listing only lines with old topic name in
  • highlight text to be changed
  • User can deselect any they don't want changing. Does all Webs
• more use of oops

-- JohnTalintyre - 19 Feb 2001

Finding exactly all topics that point to the topic to be renamed can be challenging. For example all these links (shown in edit mode) point to WebNotify in the TWiki.TWiki web (assuming you are in that web):

• WebNotify, TWiki.WebNotify, %TWIKIWEB%.WebNotify
• [[ web notify ]], [[TWiki.web notify]], [[%TWIKIWEB%.web notify]]
• %INCLUDE{"WebNotify"}, %INCLUDE{"TWiki.WebNotify"}, %INCLUDE{"%TWIKIWEB%.WebNotify"}.
• %INCLUDE{WebNotify}, %INCLUDE{TWiki.WebNotify}, %INCLUDE{%TWIKIWEB%.WebNotify}.
• [[web notify@MyAnchor]], [[TWiki.web notify@MyAnchor]], [[%TWIKIWEB%.web notify@MyAnchor]] (AutomaticNamedAnchorLinks is in latest Alpha)
• [[notification][WebNotify]], [[notification][TWiki.web notify]], [[notification][%TWIKIWEB%.web notify@MyAnchor]] (ArbitraryTextForWikiWordLinks is in latest Alpha)

You need also make sure that WebNotify in other webs are not found by mistake (the current Ref-By is not accurate, it shows sometimes topics of the same name located in other webs.

-- PeterThoeny - 24 Feb 2001

Peter, I agree that it seems hard to find all correct references to a topic, but... shouldn't the Reffered-by search (which i am not currently using) successfully find all of them, and then we should re-use that code.. (I was starting to worry about the fact that I was re-writing code that existed elsewhere..)

-- SvenDowideit - 25 Feb 2001

Mod now moved to Store.pm and Search.pm. I'll attach tomorrow. The change to Search means:

• Matches to be changed listed for all Webs
• User can deselect any that are wrong - so even if search is not perfect it should be usable.

One plus of the current TWiki is that it's not easy for someone to mess up the site. However, renaming topics has more potential. For instance how do you reverse changes? Changes to referring pages are under revision control. However, it's not so clear where the topic came from. I was wondering about a history file e.g. when moving Fromweb.Fromtopic to Toweb.Totopic we would create a file Fromweb/Fromtopic.link with the contents Toweb.Totopic. This has two advantages: 1. View could be modified to put up a re-direct message for Fromweb/Fromtopic 2. A clear record of the change is made. If a link file already existed when a rename was done, then the new link could be prepended to the file. Such a file could also be used to link the other way e.g.

Fromweb.Fromtopic -> Toweb.Totopic Fromweb/Fromtopic.link = To:Toweb.Totopic Toweb/Totopic.link = From:Fromweb.Fromtopic

This would make it easy to under a move (or possibly a DeleteTopic).

If rename is used for DeleteTopic this can easily be done if all Topic move to the Web Trash, but with no sub-webs. Sub-webs can then be supported when all of TWiki can do sub-webs. Only problem with lack of sub-webs will be possible name collisions. The link mechanism above could deal with this a topic name can be modified on move to Trash Web, then re-created if required.

As links to trashed topics would still exist, I think view should be modified to clearly show when users has moved to a deleted page.

I've put a rename link at the bottom of each page. This bring up a dialogue that let's you specifiy new web (to be a drop down) plus new topic name. Seach extract give choice on references to be changed.

A question - is it okay to rename to/from Trash or should there be an explicit delete/undelete?

-- JohnTalintyre - 26 Feb 2001

I don't feel a need for an "explicit delete" (at least not yet -- we only have about 250 topics or so). Instead, I'm planning (as administrator) to "empty the trash" of old stuff every year or so.

I've uploaded the version I have as "rename". It is based on the 19Feb01 version and handles fixing the attachments directory and allows for renaming between directories (including multilevel webs).

-- StanleyKnutson - 23 Mar 2001

This capability is going into the core, see TWikiReleaseSpring2001. A partly operational version is already in CVS. There's still work to do on correctly identifying link to "repair" - help would be most welcome.

-- JohnTalintyre - 26 Mar 2001

After two months of using TWiki at work we have some 230 topics, many of which now need renaming. Does the backend stuff you have created facilitate the addition of a MassRenameTool, such that someone can type or select 50 or so topics at a time and have them all renamed? I'd want the default new name to be the old name.

If this is not a frontend facility you have built I think I could find the resources to build this. I'd not want to get involved with the backend issues at present.

Thanks.

-- MartinCleaver - 26 Mar 2001

A good point Martin. TWiki::Store::renameTopic does the move of the topic, but doesn't fix references, this is done in rename, and is interactive i.e. user choses which links to change. Wouldn't be difficult to move the reference fixing code to a module. However, changing 50 topics interactively shouldn't be that painful.

-- JohnTalintyre - 29 Mar 2001

I confess that I haven't looked at the beta code yet but will or should the new code perform a search and replace of the old topic name with the new topic name in the log files?

Also, I would suggest that any process, whether interactive or automatic, that changes topic references in refering topics check for a TWiki site preference variable to determine whether affected topics are regarded as having 'minor change, don't notify' or be included in the next round of notifications. From a user standpoint, getting a change notification that 50 documents have been updated that I would have absolutely no reason to want to see would be very annoying. One could modify the mailnotify script to report renamed topics if that would be of interest to wiki users. By the way, would renamed topics show up in the notification email as being recently modified because they would appear as a brand new topic?

-- RussellTiller - 30 Mar 2001

Please see TWikiObjects for an alternate idea for implementing rename (and creating a general framework for a host of other goodies).

-- DavidLeBlanc - 30 Mar 2001

On to do thing is to rename also the entries in the log file of the current month. This is because statistics updates the WeStatistics topic of the current month. (I don't think we need to rename logs of previous month)

-- PeterThoeny - 31 Mar 2001

Good point on the notification, I'll check what's happening there. I'll also look at the log files, although isn't it a bit questionable changing these?

Some other problems that I need to fix.

1. Block/warn changes of key pages e.g. WebHome
2. Don't change contents of WebStatistics page?
3. Need to do different search for current and other webs
4. Incorrectly matches e.g TestTopic1->TestTopic11 causes TestTopic10->TestTopic110

-- JohnTalintyre - 27 Apr 2001

A quick thought - is there going to be some way of automatically taking people to the new page name if they have bookmarked the old page? If not, how keeping a WebRenamed topic that lists all the old page names, their new equivalent, who renamed, and on what date. On topic view if the page does not exist the view script could then tell the person where to find the content.

Another question - does the script handle moving a topic between webs?

-- MartinCleaver - 29 Apr 2001

I've thought a lot about being able to re-direct from old URL. At present the meta information in the destination topic contains the information. I was thinking of all keeping the old topic, but with just meta information point to the new. However, this brings in various complications. So for now, I propose as slight modification to search, so that it can search for any meta data, including topic moves.

Yes - moves between Web are handled, one Web can be Trash, so that topics can be deleted.

-- JohnTalintyre - 30 Apr 2001

For those interested in adding this to your own TWiki site (ie. can't wait for the spring release), I modified (and uploaded) the rename script to use a template and made a template that has fields for destination web and destination topic name. So to deploy here's what I did:

• copy rename into wiki/bin
• copy rename.tmpl into wiki/templates
• added "Rename" link to bottom of view.tmpl by copying "Attach" link

The rename template includes a suggestion to delete by "renaming" to the Trash web. If you don't have Trash web, you will want to create one or remove the suggestion.

-- BruceWilson - 13 May 2001

I just edited the top part of this page for grammar, punctuation, clarity, etc - I wasn't 100% sure about the meaning of the referring-pages paragraph at the end, so my edits may or may not make sense there. I think the middle sentence of the last para should read "Next, all topics across all Webs (including the current one) are listed that match _web.topic_" - presumably this feature does not list Webs, it lists topics?

-- RichardDonkin - 14 May 2001

Peter suggested above that entries in the log file for the current month be changed, so that the statistics script which produces the WebStatistics pages gives actual topics, rather than ones that have been renamed. I think it would be better for the statistics script to find and use the rename entries in the log, as altering a log seems undesirable if there is an alternative. Thoughts?

-- JohnTalintyre - 22 May 2001

Sorry, I hadn't noticed your question here before today. I assume the question is whether to record the new topic name or the old topic name in the log. In one sense, either could work, but recording the original topic name seems to become less useful as time goes on -- people casually looking at the log would not know what page was being viewed.

(Sorry, I haven't read the rest of this page thoroughly, and maybe I should do that before commenting any further. Just at first glance I think I'd like the log to refer to the current name of a topic, but have some mechanism to know that the topic was renamed, and have a mechanism to find the original name of the page. IIRC, there were some plans discussed above to keep a record of name changes.)

(Sorry, it's a bad day for reading.)

-- RandyKramer - 14 Jun 2001

This above is a mis-understanding. Before the TopicRename entries in the log will have the old name, then there is a rename entry, further entries for the renamed topic will have the new name. However, the statistics page will be left with both, except the old name will have a broken link. Possibilities:

• Change statistics code to notice the rename, all stats to be against the new name
• Change the log when rename is done

I favour the first option, but the statistics script isn't that easy to undertand, so I've yet to make the change.

-- JohnTalintyre - 14 Jun 2001

Im running the Sep2001 code and Ive noticed that rename does not rename the meta-data for parent references. In essence what is happening is that if you rename a parent topic, all of its children become orphans because they keep the reference to the old topic name.

Am I nuts or is this a true defect??

-- JohnCavanaugh - 31 Jan 2003

Parent references in Meta data certainly used to get updated, they still do at my older config at work. If this remains a problem then please raise a bug report.

-- JohnTalintyre - 10 Sep 2003