rockbox/manual/configure_rockbox/bookmarking.tex

% $Id$ %
\section{\label{ref:Bookmarkconfigactual}Bookmarking}
  Bookmarks allow you to save your current position within a track so that 
  you can return to it at a later time. Bookmarks also store rate, pitch
  and speed information from the \setting{Pitch Screen} (see
  \reference{sec:pitchscreen}). Bookmarks are saved on a per directory
  basis or for individual (saved) playlists. You can store multiple bookmarks,
  even for the same track. When there's already a bookmark for a directory or
  playlist, new bookmarks are added before existing ones.

  Bookmarks are stored next to the directory or playlist they reference, in a
  file with the same name as the directory or playlist and a ``.bmark''
  extension. To load a bookmark, select the bookmark file and then select
  the bookmark to load. There are other ways to load a bookmarks mentioned
  below.

  You can also configure what directories will save bookmarks by creating a file
  named 'bookmark.ignore' in a directory if you would like to never create a bookmark
  when files are played from it.

  \note{You can still manually create a bookmark but ignored directories will
         not update existing bookmarks nor auto create them for files located
         in ignored directories. }

  The file 'bookmark.unignore' provides the opposite functionality.
  For instance in the root of the drive you could create '/bookmark.ignore'
  and no files played from this drive would get bookmarks.
  If you then created '/podcasts/bookmark.unignore' tracks played from the podcast
  directory would get bookmarks.

  \note{If the current playlist has been modified or is unsaved, such as when
        playing tracks from the \setting{Database}, Rockbox will automatically
        offer to save the playlist to a file when you attempt to create a bookmark. 
        Queued tracks (see \reference{ref:queuing}) do not get saved to the playlist file.
        You're asked to confirm their removal when saving, so that the current playlist
        can be bookmarked. }

  \begin{description}

  \item [Bookmark on Stop.]
    This option controls whether Rockbox creates a bookmark when playback is
    stopped manually.
    \begin{description}
      \item[No.]
            Do not create bookmarks.
      \item[Yes.]
            Always create bookmarks.
      \item[Ask.]
            Ask if a bookmark should be created.
      \item[Yes -- Recent Only.]
            Always create a bookmark, but only in the recent bookmarks list.
      \item[Ask -- Recent Only.]
            Ask if a bookmark should be created, but only add it to the recent
            bookmarks list.
    \end{description}
    When either \setting{Yes -- Recent Only} or \setting{Ask -- Recent Only}
    is selected, bookmarks are only created if the \setting{Maintain a List
    of Recent Bookmarks} is enabled.
    \note{The \setting{Resume} function remembers your position in the most
      recently accessed track regardless of how the \setting{Bookmark on Stop}
      option is set.}
    
  \item [Update on Stop.]
    If set to ``No'', this setting has no effect and does not affect any other settings.
    If set to ``Yes'', and the file
    to which a new bookmark would be added already exists, this option overrides
    the previous setting (\setting{Bookmark on Stop}) and unconditionally creates a
    bookmark. This is useful if you don't generally want to create bookmarks but
    only want to add them to already existing bookmark files. In this case you
    should set the setting \setting{Bookmark on Stop} to ``No'' and the setting
    \setting{Update on Stop} to ``Yes''.

  \item [Load Last Bookmark.]
    This option controls if Rockbox should automatically load a bookmark for
    a file, when that file is played.
    
    \begin{description}
      \item[No]
            Always start from the beginning of the track or playlist.
      \item[Yes]
            Automatically return to the position of the last bookmark. Start
            from the beginning if there are no bookmarks.
      \item[Ask]
            Ask if playback should start from the beginning of the track or
            from one of the bookmarks.
    \end{description}

  \item [Maintain a list of Recent Bookmarks.]
    If this option is enabled, a list of the most recently created bookmarks
    may be accessed through the \setting{Recent Bookmarks} option in the
    \setting{Main Menu}. This list contains up to ten entries.
    
    \begin{description}
      \item[No]
            Do not keep a list of recently used bookmarks. This also removes
            the \setting{Recent Bookmarks} from the \setting{Main Menu}.
      \item[Yes]
            Keep a list of recently used bookmarks. Each new bookmark is added
            to the list of recent bookmarks.
      \item[One per playlist]
            Add each new bookmark to the list of recently used bookmarks, but
            only keep one bookmark from the current directory or playlist; any
            previous entries for the playlist are removed.
      \item[One per track]
            Add each new bookmark to the list of recently used bookmarks, but
            only keep one bookmark from the current directory or playlist and
            the current track; any previous entries for the track within the
            playlist are removed.
    \end{description}
\end{description}

The following keys can be used to navigate in any bookmark list.
  \begin{btnmap}
      \ActionStdNext
      \opt{HAVEREMOTEKEYMAP}{& \ActionRCStdNext}
      & Selects the next bookmark.\\
      %
      \ActionStdPrev
      \opt{HAVEREMOTEKEYMAP}{& \ActionRCStdPrev}
      & Selects the previous bookmark.\\
      %
      \ActionStdOk
      \opt{HAVEREMOTEKEYMAP}{& \ActionRCStdOk}
      & Resumes from the selected bookmark.\\
      %
      \ActionStdCancel
      \opt{HAVEREMOTEKEYMAP}{& \ActionRCStdCancel}
      & Exits Recent Bookmark menu\\
      %
      \nopt{GIGABEAT_S_PAD}{\ActionBmDelete
      \opt{HAVEREMOTEKEYMAP}{& \ActionRCBmDelete}
      & Deletes the currently selected bookmark\\}
      %
      \ActionStdContext
      \opt{HAVEREMOTEKEYMAP}{& \ActionRCStdContext}
      & Enters the context menu for the selected bookmark.\\
  \end{btnmap}

There are two options in the context menu:

\begin{itemize}
  \item \setting{Resume} will commence playback of the currently selected bookmark entry.
  \item \setting{Delete} will remove the currently selected bookmark entry from the list.
\end{itemize}