|Thread title||Replies||Last modified|
|Suggested names for Amarok manual||11||18:23, 1 December 2011|
|Amarok Manual: Some Issues Left||1||18:12, 19 October 2011|
|Our ToDo - Collections||2||23:19, 3 December 2010|
|As you can see in the discussion following this, the shortening of file names that was proposed will create great problems for the conversion of the manual to DocBook format. Consequently, we will definitely not go ahead with it.|
Page names for the manual pages have become awfully long. It is suggested that we rename them. Since page names doesn't have to reflect document structure, we can avoid to much nesting. The following is a suggestion | - feel free to modify anything you don't like.
(The Amarok/Manual prefix is left out)
|Title||Existing pagename||suggested new name|
|Quick Start Guide||QuickStartGuide||Guide|
|- Getting started||QuickStartGuide/GettingStarted||Guide/GettingStarted|
|- The Amarok window||QuickStartGuide/TheAmarokWindow||Guide/TheAmarokWindow|
|- The Music Collection||QuickStartGuide/TheMusicCollection||Guide/TheMusicCollection|
|- The Context View||QuickStartGuide/TheContextView||Guide/TheContextView|
|- How to deal with problems||QuickStartGuide/HowToDealWithProblems||Guide/Problems|
|The Amarok Window||AmarokWindow||AmarokWindow|
|- The Media Sources Pane||AmarokWindow/MediaSources||MediaSources|
|- The Context Pane||AmarokWindow/ContextPane||ContextPane|
|- The Playlist Pane||AmarokWindow/PlaylistPane||PlaylistPane|
|- Changing Layouts||ConfiguringAmarok/ChangingLayouts||ChangingLayouts|
|-- Collection Scanning||Organization/Collection/CollectionScanning||Scanning|
|-- Search in Collection||Organization/Collection/SearchinCollection||Searching|
|-- Organize Collection||Organization/Collection/OrganizeCollection||Organize|
|-- Remote Collections||Organization/Collection/RemoteCollections||RemoteCollections|
|--- Universal Plug and Play (UPnP)||Organization/Collection/RemoteCollections/UPnP||UPnP|
|-- External Database||Organization/Collection/ExternalDatabase||ExternalDatabase|
|-- Working with Media Devices||Organization/Collection/WorkingWithMediaDevices||MediaDevices|
|- Cover Manager||Organization/CoverManager||CoverManager|
|- Tag Editor||Organization/TagEditor||TagEditor|
|- Script Manager||Organization/ScriptManager||ScriptManager|
|- Saved Playlists||Playlist/SavedPlaylists||SavedPlaylists|
|- Playlist Filtering||Playlist/PlaylistFiltering||PlaylistFiltering|
|- Queue Manager||Playlist/QueueManager||QueueManager|
|- Dynamic Playlists||Playlist/DynamicPlaylists||DynamicPlaylists|
|- Automatic Playlist Generator||Playlist/AutomaticPlaylistGenerator||AutomaticPlaylist|
|- The Moodbar||Various/Moodbar||Moodbar|
|- Amarok on other Platforma||Various/AmarokOnOtherPlatforms||OtherPlatforms|
|-- Amarok on Non-KDE Desktops||Various/AmarokOnOtherPlatforms/NonKDE Desktops||NonKDE Desktops|
|-- Amarok on Windows||Various/AmarokOnOtherPlatforms/Windows||Windows|
|-- Amarok on OS X||Various/AmarokOnOtherPlatforms/OSX||OSX|
|- Troubleshooting and Common Problems||Various/TroubleshootingAndCommonProblems||Troubleshooting|
|- Frequently Asked Questions||Various/FAQ||FAQ|
|- Amarok Top-level Menus||References/MenuAndCommandReference||Top-levelMenus|
|- Amarok Menu||References/MenuAndCommandReference/AmarokMenu||AmarokMenu|
|- View Menu||References/MenuAndCommandReference/ViewMenu||ViewMenu|
|- Playlist Menu||References/MenuAndCommandReference/Playlist||PlaylistMenu|
|- Tools Menu||References/MenuAndCommandReference/Tools||ToolsMenu|
|- Settings Menu||References/MenuAndCommandReference/Settings||SettingsMenu|
|- Help Menu||References/MenuAndCommandReference/Help||HelpMenu|
|- Default Global Shortcuts||References/KeybindingReference/GlobalShortcuts||GlobalShortcuts|
|- Amarok Shortcuts||References/KeybindingReference/AmarokShortcuts||AmarokShortcuts|
|Credits and License||References/Credits and License||Credits|
Please do not do this bulk rename. It breaks DocBook generation definitely and completely and means nothing to usability or ease up translation efforts (just renaming for the sake of renaming).
Moreover, it breaks all existing translations for absolutely no reason.
Obviously we won't break the DocBook generation. I don't understand it, though. I was of the impression, that page names didn't matter - only chapter and section names.
Eehmmm. If you rename a page you should fix:
What is the sense then?
Can you explain the sense of this renaming? Is there some algorithm to choose the page name? Should it be an arbitrary unique set of characters? Why not use just "Chapter_1", "Chapter_2", etc. ? (just joking)
The idea of changing page names were made on the assumption, that the DocBook conversion doesn't care about page names - I thought that was the case, so I don't understand why you would need to make a special hack for this. Have I misunderstood your explanation?
The idea of reworking the whole organization of the Amarok Manual including page names is not a new one. It was part of the discussions we had some time ago. For various reasons the process went on hold a bit, but I don't recall anyone expressed misgivings back then - off cause the whole discussion was a bit disorganized, so maybe this was just missed.
Annew and I considered this change because we think that long page names are troublesome (and some of the Amarok page names are really long). Annews main concern is UserBase readers. I actually think they should also be a concern for writers and translators. Shorter links are easier to read (and write) and don't obscure the surrounding text as much as (very) long links.
It is intended to be a "one time only"-affair. In fact I think that not tying page names to the structure of the document is a good thing - that way, if the writers later decides to restructure the manual, they can move pages around by just changing the ToC and PrevNext links - nothing else would need to change.
Off course the advantages of a new naming scheme must be balanced against the work imposed on all of us right now, and if it disrupts the DocBook generation, I doubt it will be worth it to go through with this proposal.
The last version of Amarok Manual can be flawlessly extracted from UserBase as docbook in a few minutes (mostly waiting for the images to download). However some issues left:
1. The following pages have the names and ToC items that are differ from section names
That leads to the external links in the converted docbook.
2. Amarok/Manual/AdvancedFeatures/ScriptManager has a reference in the Manual but has no ToC item, thus does not included in the docbook.
3. The resulting Manual is ~11MB of size. Any packaging news from Amarok Team?
Any thoughts about solving these issues?
Thanks in advance for your answers.
P.S. The docbook (without images, to save your time they are downloaded as expected here ) can be found here. Comments and suggestions are welcome. Instructions on how to convert by yourself can be found here.
Now that we have 2.3.2 out the door, and I've got the Insider 15 published, I'm looking forward to finishing this Handbook. One thing I've noticed is that CD Ripping isn't covered. Perhaps we can go
1. Organizing your collection 2. Tell Amarok where it is 3. Search your Collection 4. Adding to your collection a. ripping CDs b. moving other tracks in from Files 5. Other Devices
then Remote Collections
Hm, the order seems wrong to me, Organizing your collection shouldn't be the first step IMHO as it normally is not even necessary for most users. But ripping CDs is a subset of copying to collection, that is correct. We should go from the most basic to the most complex feature, and organizing the collection is definitely an advanced feature. Remember we have an Advanced Feature section in the menu :)
I think we were misunderstanding one another here -- when I said organizing your collection, I was speaking of basic organization of the collection, not the Organize Collection Amarok function, which truly is advanced. I've never ventured to test it out.
In any case, my remark is old and out-dated.