Talk:Amarok/Manual

Jump to: navigation, search

Contents

Thread titleRepliesLast modified
Suggested names for Amarok manual1117:23, 1 December 2011
Amarok Manual: Some Issues Left117:12, 19 October 2011
Our ToDo - Collections222:19, 3 December 2010

Suggested names for Amarok manual

Edited by author.
Last edit: 17:23, 1 December 2011
Flag-red.png
 
Remember
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
Introduction Introduction Introduction
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
- Playlists QuickStartGuide/Playlists Guide/Playlists
- The Context View QuickStartGuide/TheContextView Guide/TheContextView
- How to deal with problems QuickStartGuide/HowToDealWithProblems Guide/Problems
- GLOSSARY QuickStartGuide/Glossary Guide/Glossary
The Amarok Window AmarokWindow AmarokWindow
- Toolbar AmarokWindow/Toolbar Toolbar
- The Media Sources Pane AmarokWindow/MediaSources MediaSources
- The Context Pane AmarokWindow/ContextPane ContextPane
- The Playlist Pane AmarokWindow/PlaylistPane PlaylistPane
Configuring Amarok ConfiguringAmarok Configuration
- Changing Layouts ConfiguringAmarok/ChangingLayouts ChangingLayouts
Organization Organization Organization
- Collection Organization/Collection Collection
-- 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
--- Ampache Organization/Collection/RemoteCollections/Ampache Ampache
--- DAAP Organization/Collection/RemoteCollections/DAAP DAAP
--- Samba Organization/Collection/RemoteCollections/Samba Samba
--- 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
- Transcoding Organization/Transcoding Transcoding
- Script Manager Organization/ScriptManager ScriptManager
Playlist Playlist Playlist
- 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
Various Various Various
- 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
References References References
- 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
Keybinding Reference References/KeybindingReference Keybindings
- Default Global Shortcuts References/KeybindingReference/GlobalShortcuts GlobalShortcuts
- Amarok Shortcuts References/KeybindingReference/AmarokShortcuts AmarokShortcuts
Credits and License References/Credits and License Credits
Claus chr14:38, 30 November 2011

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.

Yurchor16:08, 30 November 2011

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.

Claus chr16:21, 30 November 2011

Eehmmm. If you rename a page you should fix:

  • all the links;
  • all translations;
  • i should use another ugly hack to fix the script just only for this version of Amarok manual (until the next refactoring of names). It will be easier then just hardcode the set of chapters (sections, subsections, subsubsections) in some file that the renamers should maintain in actual state.

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) Face-smile.png

Yurchor16:40, 30 November 2011

Your first two points goes without saying - we did think of that Face-smile.png

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.

Claus chr18:39, 30 November 2011
  1. There is misunderstanding here: converter does not take into account page names, but since you change links (certainly you should change the links then) there will be no way to guess what is the initial reference point. You can add the anchor, but there will be no gain (the link becomes long) just looses (re-translation).
  2. I cannot understand the point. Is there a plan that include user's link exchange links on Amarok pages? If so, it will be better to use Wiki search system and just point user with words "You should search on UserBase (in embedded manual)." Am I right?
Yurchor19:36, 30 November 2011
 
 
 
 
 

Amarok Manual: Some Issues Left

Hi!

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

Amarok/Manual/Organization/Collection/RemoteCollections/DAAP

Amarok/Manual/Organization/Collection/RemoteCollections/UPnP

Amarok/Manual/Various/AmarokOnOtherPlatforms/NonKDE_Desktops

Amarok/Manual/Various/AmarokOnOtherPlatforms/Windows

Amarok/Manual/Various/AmarokOnOtherPlatforms/OSX

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 Face-smile.png) can be found here. Comments and suggestions are welcome. Instructions on how to convert by yourself can be found here.

Yurchor17:09, 12 October 2011

1. The names will be changed

2. Has been added to the ToC

3. It's a big manual with many images. I'm not sure we can do much about that

Claus chr17:12, 19 October 2011
 

Our ToDo - Collections

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

Local Collection

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

Valorie08:21, 20 September 2010

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 :)

Mamarok20:08, 21 September 2010
 

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.

Valorie22:19, 3 December 2010
 

This page was last modified on 20 September 2010, at 08:21. Content is available under Creative Commons License SA 4.0 unless otherwise noted.