[wiki] Tags Reference

Destry · 2008-10-07 09:13:54

Let’s give this important topic it’s own thread.

Yesterday, I created a custom namespace called txp: I completely forgot the old tag pages all began with that prefix (which was not good page title planning back in the day). In fact, when you create a custom namespace any existing pages in that namespace ~~go bye-bye~~ disappear, and ~~it’s not simply a matter of deleting the custom namespace, you have to reload the database from the dump file, or query all the pages~~ you have to delete the custom namespace to get them back. (Ed. see next post for the real culprit.)

Last edited by Destry (2008-10-07 09:35:04)

Destry · 2008-10-07 09:32:02

hakjoon wrote:

There seems to be something that is forcing all the urls to lower case which I think is making all the old links not work. I can’t track down what it is though.

This made me think to try deactivating the “unforce capitalization” line in TextBookSetting.inc. (Also something recently added to allow lowercase page titles as needed, for example, with Tag pages.)

This fixed the problem.

This indicates a few things based on this and other testing experiments at the demo site:

You do not lose page content if you accidentally use a custom namespace for pages already using such a prefix. All you need to do is remove the custom namespace configuration and the pages are recovered.
The “unforce capitalization” config is not recursive. It only applies to new pages created after the config has been implemented (i.e. if there had a been a lazy title “the big dig” prior to the config, that page would still appear as “The big dig” even after the config.
The same is not true the other way…any page that was titled lowercase after the config (thus effectively appearing lowercase), it will be forced back to an all-cap if the config is ever removed. (Will it revert again if the config is put back in place? That needs tested.)
Title prefixes (e.g., txp:) do not revert like normal titles in #3, instead their content remains disappeared.

What it comes down to is that using wiki conventions (e.g., title prefixes) for reasons other than what they are intended for (namespaces) prevents the ability to use other wiki functions, like being able to use the “no force caps” config to prevent the default forced caps behavior, thus such prefixes should be avoided.

Ed. Bringing this discussion here too, which is relevant.

Ed. Directing focus to next post.

Last edited by Destry (2008-10-07 13:38:07)

Destry · 2008-10-07 13:37:05

I hate making consecutive posts (especially long ones), but the Tags Reference is a key part of TextBook and I’m linking to this post from here to get more feedback. Decisions need made, and the first several responders (representing wiki readers AND authors) will probably inform the decision.

SITUATION

The current Tags Reference is a wiki gem; however it can be better in three important ways:

Tag page titles can be more human-friendly by making them less syntaxy (i.e., dropping the “txp:” and the trailing “/” to give something like “article_custom” alone.)
Make page maintenance easier over time.
The entire suite of pages making up the Tags Reference can be printed in a single file (an often wished/inquired feature).

We can make these things happen, but it requires recreating the pages with new titles and using a wiki category (proposing category:Tags Reference). By using a category, we can replace the need for an Alphabetical Listing page and simply let the category page do that for us. More significantly, the category is what makes it possible to use the PDF Book extension to print the entire Tags Reference as a single pdf doc.

Considering the benefits, I don’t think anyone would argue using a category so far. However, there’s another aspect to consider and decide upon, and that is with the tag page titles themselves.

Part of improving wiki architecture over time is to improve page titles. It was mentioned how to edit them above, but it might also be effective to title them in lowercase too, which is a common convention when using code syntax in documentation titles and headers. This would be done to help distinguish tag pages from all other English title pages; e.g., article (tag page) vs. Articles (admin-side page). By default MW forces an all-cap behavior whether you type lowercase or not. This can be undone with a config change in the wiki, but once done it should never be undone or it could cause problems in the future with anything in either the “template:” or custom (if any) namespaces. The other nice thing about this approach is it leaves the title semantics clean — only the tag name itself, which is the same logic being applied to the admin-side panel pages too (e.g., Write instead of Write Subtab).

An alternative to lower-casing tag page titles, thus not messing with the config mod at all, would be to add something to the tag page titles that better indicate it’s about a tag, e.g.: Article Tag, Article_custom Tag, etc. Note, this goes against the grain of making titles cleaner and more correct with convention (lowercase code in titles/headers), but still allows the pages to be alphabetized in the category. There’s another risk with this approach too, with regard to wiki authors; adding something like “Tag” to the page title will likely increase the need for authors to create a lot of alternate link labels when refering to pages in inline copy, and authors are an important consideration in wikis as much as wiki readers. In that respect, which wiki link option below is both easier to type and visually more appealing?

[[article_custom Tag]] —> article_custom Tag (more to type and not a pretty link)
[[article_custom Tag|article_custom]] tag —> article_custom tag (lots more to type to get the pretty link)
[[article_custom]] tag —> article_custom tag (clean typing and the pretty link too)

To my mind, #3 is the right choice.

Anyway, that’s the background to the decision making. What’s needed then is decisions in the following order:

Do we go with a category to gain organization and printing advantages?
- If yes, it will be called “category:Tags Reference”
- If no, the existing “Alphabetical Tag Listing” page will be renamed to “Tags Reference” and the alphabetic lists maintained by hand.
Do we rename tag pages? If yes do we use…
1. clean tag name labels in lowercase (e.g., article_custom),
2. lowercase and a “Tag” extension on the label (e.g., aritcle_custom Tag), or
3. forego lowercase entirely and use the extension (e.g., Article_custom Tag)?

PROCESS FOLLOWING DECISION

If, IF, the feeling is to go with a category and edit titles down to something clean, conventional and consistent in the wiki, this is how it will need to happen if lowercase titles are the aim, because using the config to unforce all-caps can not be used in any other order due to the unfortunate use of the “txp:” prefix on the existing tag pages originally:

Add new page links (reflecting the new page title syntax), next to the existing counterparts in the existing Alphabetical listing. These should not yet be populated with content, just available to make it easier later.
copy the content of each old tag page and save as a .txt file temporarily. (If this is not done, the content will disappear and be unavailable in next step.)
Add the “unforce capitalizations” config.
Copy/paste the tag page content from .txt files to their new pages having lowercase titles and no prefixes.

The last step reflects the only Tags Reference downtime, and it wouldn’t be more than about 30 minutes or so as the new pages were populated with the pasted content, which is the point of step 1, to facilitate this in a systematic way. Afterwards, the new pages can be tagged into the category and the old pages removed from the wiki.

Please, when responding to these ideas, indicate if you are mainly a wiki reader, author, or fairly both.

Last edited by Destry (2008-10-07 13:39:01)

Bloke · 2008-10-07 14:02:07

I’m currently a wiki reader. Author requested.

My feeling is for 1) category: Tags Reference and 2) clean tag labels, since that makes most sense to me. Also gives more freedom when referencing because it gives a choice of phrasing:

… you can also use the article_custom tag to achieve a similar effect.

or

… you can also use article_custom to achieve a similar effect.

With the forced ‘Tag’ on the end you would be obliged to use the first syntax for correct English. Plus, doesn’t it ease translation because the word ‘Tag’ won’t need to be changed in every doc title?

Last edited by Bloke (2008-10-07 14:03:10)

els · 2008-10-07 14:30:55

Same for me. So 1-1 and 2-1. So far I’m a reader only but still planning to contribute to the wiki, and I see more advantages than drawbacks for both sides.

hakjoon · 2008-10-07 15:21:54

Good, you had better luck with the settings then I did. Maybe it was the custom name space clash, because I tried resetting that variable in local settings and nothing happened.

there seems to be CapsCleanup script you can run, also I was thinking we could uppercase the link text in the old tags index page which should make them work. From what I understand $wgInitialCaps (or whatever it is) being false makes the links case sensitive, but when it’s true the initial letter is always capitalized regardless of the original link text.

Destry · 2008-10-08 08:14:38

@Bloke and Els: Noted.

@hak (and the curious followers): I think you’re right, there was a clash with the “txp:” custom namespace, but mainly because pages existed that way before the namespace was put into affect. However, I think the key in all of this was not so much the namespaces but the state of the titles prior to using the no-caps config (i.e., CapitalLinks = false). MW forces all titles to begin with cap by default. Thus even if a page was written in lowercase (e.g., any of the old tag pages), it’s still hard-saved as a cap. For some reason when you tell MW to start recognizing lowercase, it’s not recursive, it only begins with new pages created from the time the no-caps config is implemented, so any existing pages that had lowercase need recreated, though this is certainly complicated by the fact the “txp:” prefix already existed on those pages.

I also witnessed this in the demo site for templates I had created before using the no-caps config. The templates were originally named with lowercase (e.g., {{mininav}} giving [[template:mininav]]). After implementing the no-caps config, all templates having lowercase titles disappeared (same as with custom namespaces). To bring them back, I simply had to change the template link referrer to begin with a cap (i.e., {{Mininav}}) because MW had auto-converted the lowercase to uppercase and that became the new working path. Strange and confusing to the stumbler who stumbles upon it, but not devastating. However, the fact that normal pages do not disappear suggests there is a strange effect related with prefixed pages only. Bottom line is always use prefixes as MW expects them to be used and you’ll eliminate half the hair-pulling (or beard-tugging). :)

Exception:
I did not know about that CleanupCaps script, very interesting, and certainly something to put in the toolbox. It appears to have been created exactly for when the no-caps config is used later in the life of a wiki. The script’s author (Brion Vibber) is one of the principle MW devs, so it’s certainly valid in that respect. However, I skeptical it will work in this situation with tag pages specifically, even if we didn’t want to change tag page titles, because (remembering) we have pages that are prefixed with “txp:” which is confusing MW to begin with.

Maybe it would be worthwhile to keep my demo wiki online (albeit behind a password access) and use it to trial-run such scripts in the future. Even better, a sister TxB wiki at .net which is password-protected for admin sandbox testing only.

More immediately, with the need for changing the tag page titles, I think we’ll have to follow the manual method and create the temp .txt files to paste them back in later.

Last edited by Destry (2008-10-08 08:19:11)

ruud · 2008-10-08 18:05:56

1-2, because showing “Category: Tags” is confusing: “category: tags” vs “category tags”. The former uses category for organizational purposes, while the later refers to the tags for TXP categories. I think the use of the word category should be avoided when organizing stuff in Textbook. If that’s possible with 1-1, then the advantages do outweigh the disadvantages.

2-1, sure.

alanfluff · 2008-10-08 19:06:59

1-1 and 2-1.

Agree with rudd that 1-1 might introduce a little confusion, but the advantage of dropping the ‘…maintained by hand…’ element wins it for me (as a user of the resource, I am indebted to those that maintain it and I wish the least work for them). Were it to be 1-1, might a broken-out explanatory note suffice to advise of the possible confusion (guessing here, sorry if I am missing the point).

My thanks to everyone who maintains this brilliant resource.

els · 2008-10-08 19:30:51

The change to category:Tags Reference makes it much less confusing IMO.

Destry · 2008-10-08 21:47:01

alanfluff wrote:

the advantage of dropping the ‘…maintained by hand…’ element wins it for me (as a user of the resource, I am indebted to those that maintain it and I wish the least work for them).

Bless you.

And the advantage (from a category) of being able to print the entire reference as a single PDF should make many folks happy too. :)

Were it to be 1-1, might a broken-out explanatory note suffice to advise of the possible confusion (guessing here, sorry if I am missing the point).

That’s exactly right. Even if ruud is outvoted, we still try and provide as much solution to the concerns as we possibly can while still gaining the big benefits. In this case, we make a prominent opening line statement, like you suggest, and make the category name explicitly clear, as Els noted.

hakjoon · 2008-10-09 02:38:42

Regarding a test wiki, there already is http://textpattern.net/test-wiki/ which uses a separate DB. I used it when testing updates. It shares TextbookSettings.inc but that would be easy to change.

Last edited by hakjoon (2008-10-09 02:40:24)

Textpattern CMS

Textpattern CMS support forum

#1 2008-10-07 09:13:54

[wiki] Tags Reference

#2 2008-10-07 09:32:02

Re: [wiki] Tags Reference

#3 2008-10-07 13:37:05

Re: [wiki] Tags Reference

#4 2008-10-07 14:02:07

Re: [wiki] Tags Reference

#5 2008-10-07 14:30:55

Re: [wiki] Tags Reference

#6 2008-10-07 15:21:54

Re: [wiki] Tags Reference

#7 2008-10-08 08:14:38

Re: [wiki] Tags Reference

#8 2008-10-08 18:05:56

Re: [wiki] Tags Reference

#9 2008-10-08 19:06:59

Re: [wiki] Tags Reference

#10 2008-10-08 19:30:51

Re: [wiki] Tags Reference

#11 2008-10-08 21:47:01

Re: [wiki] Tags Reference

#12 2008-10-09 02:38:42

Re: [wiki] Tags Reference

Board footer