User:Claus chr/ToDo/Amarok

To Do

• Mark up Amarok/Manual/ConfiguringAmarok/ChangingLayout for translation.

DocBook problems

• At several places, "Amarok" has been lost in conversion!
• Configuring Amarok/Formerly Internet Services before Amarok 2.4.1, now Plugins: anything but link is lost

Suggestions

Document structure

1. Every page should have identical title and page name: Suggested structure

• Introduction
• Quick Start Guide
  • Getting Started
  • The Amarok Window
  • The Music Collection
  • Playlists
  • The Context View
  • How to deal with problems
  • Glossary
• The Amarok Window
  • Toolbar
  • Media Sources Pane
  • Context Pane
  • Playlist Pane
• Configuring Amarok
  • General
  • Collection
  • Playback
  • Notifications
  • Database
  • Plugins
  • Scripts
  • Changing Layouts
• Organization
  • Collection
  • Cover Manager
  • Tag Editor
  • Transcoding
• Playlist
  • Saved Playlists
  • Playlist Filtering
  • Queue Manager
  • Dynamic Playlists
  • Automatic Playlist Generator
• Advanced Features
  • AFT
  • Script Manager
  • Working With Media Devices
• Various
  • Moodbar
  • Amarok on other Desktops and Operating Systems
  • Troubleshooting and Common Problems
  • FAQ
• Reference
  • Menu and Command Reference
  • Keybinding Reference
  • Credits and License

Compared with the current UB TOC, the last three chapters have been merged to one Reference chapter - the original chapters are now sections. Only chapters and sections are shown in the TOC (docbook only supports two levels) - it is probably a good idea to do so in the UserBase version, too.

2. We should rename pages :( At the very least the pages listed here must be renamed. Because of mismatch between page name and page title links in the docbook to these pages don't work properly. Also, Amarok/Manual should probably be renamed Amarok/The Amarok Handbook (alternatively, the link to this page on Amarok/Manual/Introduction should be removed - as it is now, it can't link properly in docbook).

3. We need to go over all pages to ensure that every section, subsection and so on has the proper heading level. Right now a great number of them has too high a level resulting in a docbook TOC with 93 chapters and many sections!

4. Currently, the Advanced Features pages are missing from the UB TOC - are they "production ready"?

5. Perhaps the (very long) configuration page should perhaps be split?

6. (The page Amarok/Manual/Organization/CollectionScanning is placed below Amarok/Manual/Organization/Collection in the UB TOC. This doesn't seem to pose any problems, though.)

Images

7. Some images which display inline in UB cause sections to break up in two with the image displayed between "sections".

8. On some pages sections tend to run together. This is caused by long images placed besides short text sections. Solution: place </translate><br style="clear: both;"/><translate> after the troublesome section. This also works with docbook. See Amarok/Manual/AmarokWindow/PlaylistPane

---

We need guidelines for images: Are there any rules for docbook manuals?

Questions to consider:

Image size: Images ought to be contained within the regular page (at least most of them) but should be large enough to display details clearly.

Image placement: Should we allow images next to text or should images allways be centered between paragraphs?

Images needed

• action-collection-amarok in 48x48 for Amarok/QuickStartGuide/TheMusicCollection. Done!
• Preferences-other in 16x16 for Amarok/QuickStartGuide/TheMusicCollection Done!
• Amarok-merge-icon in 16x16 for Amarok/QuickStartGuide/TheMusicCollection Done!

Text

We need to go through all pages to ensure that they conform to the guidelines with respect to the use of emphasis, bolding and markup tags. Are the guidelines for docbook manuals identical to UserBase guidelines?

Old issues - some solved

On Amarok/QuickStartGuide/GettingStarted:

• The First Start Dialog: If First Start is its name it should be bolded, otherwise we should use its proper name (bolded) or a descriptive phrase (unbolded, uncapitalized). Also: isn't it really a guide?
• The blue wolf: (20px)
• The Amarok wrench icon: or (20px)
• The merge icon: or (20px)
• Replace scanned images with proper icons. Those not in the Oxygen folder should be in src/images/icons/ in git.

General issues:

• Images in image titles must go!
• How does the docbook script sequence the pages - use content page or follow PrevNext links?
  • Neither first, nor the second. API to export pages sequentially could not be found. This makes ToC parsing useless. The list of pages should be created before exporting (manually.)