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
(as it is called today) to
and change links to that page accordingly, i.e.
(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.
|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|
|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.
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
Maybe it is still a good idea to shorten that to
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?