Suggested names for Amarok manual

Let me explain more clearly:

Current manual is not structured (page can be chapter, section, subsection, anything). There is not need to fix it, it is done.
So it is reasonable to use the real structure (chapters and sections) for the referencing. Current script strips off all UB page information as the guessing on page names is almost useless and troublesome.
The script adds labels to each chapter, section, subsection etc. The formatting algorithm for the labels is as follows:
1. convert section name to lowercase (Wiki is case-ignorant,hence it's necessary step)
2. replace any forbidden characters (spaces, commas, dots, etc.) with a dash "-".
After that during parsing the script use the labels for resolving UserBase references. It compares the last part of the internal UB link with the list of labels. If there will be equivalent it replaces the link with internal DocBook reference. If not, leaves external UB reference.
Most of the UB links refer to page names, not to page titles (and you will break this if rename pages. Ex.: Troubleshooting and Common Problems would be Troubleshooting.) There is no way to predict such renaming programmatically. I used several hacks to fix current naming scheme. If you break it I'd better give up.

My idea is that no user searches for page names. Users search information (keywords) or just read manual section-by-section. Authors just copy and paste names of pages (users may not even know about them).

Yurchor‎

If I understand you correctly, you are confirming my understanding of the DocBook conversion. But maybe I haven't explained our proposal very well. As an example, we wanted to rename

userbase.kde.org/Amarok/Manual/Various/TroubleshootingAndCommonProblems

(as it is called today) to

userbase.kde.org/Amarok/Manual/Troubleshooting

and change links to that page accordingly, i.e.

[[Special:myLanguage/Amarok/Manual/Various/TroubleshootingAndCommonProblems|Troubleshooting and Common Problems]]

would become

[[Special:myLanguage/Amarok/Manual/Troubleshooting|Troubleshooting and Common Problems]]

(Troubleshooting and Common Problems is the title of the main section of that page). As I see it, DocBook conversion should be unaffected, since the actual title is intact - only the link part would change, or am I missing something?

Off course, this still leaves all the other objections to be carefully considered, even if our plan should turn out not to create problems for the DocBook conversion.

Claus chr‎

	Current naming scheme	Proposed naming scheme
Name of the page	Amarok/Manual/Various/TroubleshootingAndCommonProblems	Amarok/Manual/Troubleshooting
Title of the page	Troubleshooting and Common Problems	Troubleshooting and Common Problems
DocBook label	troubleshooting-and-common-problems	troubleshooting-and-common-problems
Last part of the address (used to find the label)	TroubleshootingAndCommonProblems	Troubleshooting
Results	Label (id) found (script assumes that camel-casing can be changed to dashed form)	Label (id) not found (troubleshooting != troubleshooting-and-common-problems)
Link in the DocBook	<link linkend="troubleshooting-and-common-problems">Troubleshooting and Common Problems</link> (internal)	<ulink url="http://userbase.kde.org/Amarok/Manual/Troubleshooting">Troubleshooting and Common Problems</ulink> (external)

So this change effectively breaks almost all internal links for no reason. I still cannot understand why cryptic short names are better than full page name, as my Opera shows (just like modern Firefox and Chrome) just a pleasant short part of the long address in address bar.

Yurchor‎

Now I get it. Thank for the explanation. The proposed scheme will naturally have to be abandoned. I still wonder, if it is a good idea to have the deep nesting levels of some of the pages, such as

Amarok/Manual/Various/AmarokOnOtherPlatforms/OSX

Maybe it is still a good idea to shorten that to

Amarok/Manual/OSX

That should be OK for DocBook, right? (Off course, there may be other reasons for not doing this.)

Btw., the section name of the OSX page is "Amarok on OS X". Does that not create problems for DocBook? Should we make guidelines for manuals that ensures consistency between ToC, page names and chapter/section titles?

Claus chr‎

The current implementation uses only the last part of the address (after the final "/" or "#"). Thus it is immune to the changes of the prefixes.

Yurchor‎