<!-- **********************************************************************
  copyright            : (C) 2000-2019
                         Rafi Yanai, Shie Erlich, Frank Schoolmeesters
                         & the Krusader Krew
  e-mail               : krusader-devel@googlegroups.com
  web site             : https://krusader.org
  description          : a Krusader Documentation File

***************************************************************************
* Permission is granted to copy, distribute and/or modify this            *
* document under the terms of the GNU Free Documentation License,         *
* Version 1.1 or any later version published by the Free Software         *
* Foundation; with no Invariant Sections, no Front-Cover Texts and        *
* no Back-Cover Texts.  A copy of the license is available on the         *
* GNU site https://www.gnu.org/licenses/fdl.html or by writing to:        *
* Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,    *
* MA 02111-1307, USA.                                                     *
*********************************************************************** -->
<sect1 id="bookman">
  <title>BookMan: Organize your Bookmarks</title>
  <indexterm>
    <primary>Bookmarks</primary>
  </indexterm>
  <para>BookMan is &krusader;'s Bookmark tool for
  bookmarking folders, local and 
  <link linkend="remote-connections">remote URLs</link>, and later
  returning to them in a click of a button. The Bookman menu is
  divided into four sections: 
  <itemizedlist>
    <listitem>
      <para>Your personal bookmarks</para>
    </listitem>
    <listitem>
      <para>Popular &URL;s</para>
    </listitem>
    <listitem>
      <para>Permanent bookmarks</para>
    </listitem>
    <listitem>
      <para>Manage bookmarks</para>
    </listitem>
  </itemizedlist></para>
  <note>
    <para>You can bookmark inside a remote file system
    (&FTP; or SAMBA) and later use the bookmark to
    quickly connect to the remote machine, but you cannot bookmark
    inside an archive.</para>
  </note>
  <figure id="screenshot-bookmanadd" float="1">
    <title>Bookmark menu</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="bookmanadd.png"></imagedata>
      </imageobject>
      <textobject>
        <phrase>Bookmark menu</phrase>
      </textobject>
    </mediaobject>
  </figure>
  <sect2 id="using_bookmarks">
    <title>Using Bookmarks</title>
    <para>Usually, you click on the 
    <guibutton>BookMan II</guibutton> button (the rightmost button to the right of
    the address bar at the top of the active panel) when you are in the target
    folder. For example, to bookmark 
    <filename class="directory">/usr/tmp</filename>, navigate
    &krusader; there and click the 
    <guibutton>BookMan II</guibutton> button and select 
    <guimenuitem>Bookmark Current</guimenuitem>. When the 
    <guilabel>Add Bookmark</guilabel> dialog box appears, the
    &URL; line will say 
    <filename class="directory">/usr/tmp</filename>. 
    <guilabel>Name</guilabel> is for the name you would like to give
    to the bookmark (&eg;: temporary folder). Hotkeys are supported
    by adding 
    <literal>&amp;</literal> to the bookmark name
    &eg;
    <literal>&amp;sourceforge, &amp;home,
    down&amp;loads</literal> &etc;, so you can
    quickly call the bookmark name with 
    <keycombo action="simul">&Alt;
    <keycap>foo</keycap></keycombo>. If you add the bookmark
    without entering a name, the bookmarks name will be the same as
    its target. 
    <guilabel>URL</guilabel>
    is where the bookmark points to. 
    <guilabel>Create in</guilabel> creates bookmark folders for
    organizing your bookmarks.</para>
    <para>To use your bookmarks, click the 
    <guibutton>BookMan II</guibutton> button and choose a bookmark.
    You may also use the <link linkend="key_bindings">Key-Bindings</link>: 
    <keycombo action="simul">&Ctrl;
    <keycap>B</keycap></keycombo> to bookmark the current item,
    <keycombo action="simul">&Alt;
    <keycap>right/left arrow</keycap></keycombo> to 
    open right/left panel bookmarks list and
    <keycombo action="simul">&Ctrl;
    <keycap>D</keycap></keycombo> to open the bookmarks of the
    active panel. From the context menu of the bookmark (&RMB; click)
    you can open it in a new 
    <link linkend="folder-tabs">Folder tab</link>.</para>
    <para>There is a quick search bar at the top of the <guibutton>BookMan II</guibutton> menu.</para>
    <note>
      <para>
        The search bar will always be visible in the bookmarks menu if you check the
        corresponding item on the <link linkend="konfig-panel-general">Panel Konfigurator's page</link>.
      </para>
    </note>
    <para>Below are the rules to handle bookmarks:</para>
    <itemizedlist>
        <listitem>
            <para>Just type letters to search: bookmarks are matched by name prefix</para>
        </listitem>
        <listitem>
            <para>If multiple bookmarks are matched by the prefix, they are highlighted and the first one is selected - hit &Enter; to activate the bookmark</para>
        </listitem>
        <listitem>
            <para>Once a single bookmark is matched, it is immediately triggered. That is when you type <literal>'h'</literal> and only one bookmark starts with <literal>'h'</literal>, it is executed immediately - no &Enter; needed</para>
        </listitem>
        <listitem>
            <para>Accelerators work only if the keystroke is the first one</para>
        </listitem>
        <listitem>
            <para>&Backspace; is supported</para>
        </listitem>
        <listitem>
            <para>Search is case insensitive unless you type a capital letter. That is typing <literal>HamBurglar</literal> will only match <literal>HamBurglar</literal> but not <literal>hamburglar</literal> or <literal>Hamburglar</literal>.</para>
        </listitem>
        <listitem>
            <para>Search bar is intentionally a read-only field</para>
        </listitem>
    </itemizedlist>
  </sect2>
  <sect2 id="password_handling">
    <title>Password handling</title>
    <para>One of the benefits of the 
    <link linkend="bookman">bookmark manager</link> is that the
    passwords are saved using &plasma;'s services - where
    &eg; your &konqueror;/&kmail;
    password are saved. If you have a wallet, &plasma; will
    save the passwords there. By clicking the bookmarks, a dialog
    will open and ask for your username and password. Supply them
    and click <guibutton>Save password</guibutton>. The passwords and usernames will be
    saved securely by &plasma;'s wallet (make sure it is
    enabled by your distro). The downside here is that if the system
    was reinstalled and you do not backup your passwords from the wallet as
    well as &krusader;'s bookmark file, something will
    be lost.</para>
  </sect2>
  <sect2 id="popular-urls">
    <title>Popular URLs</title>
    <indexterm>
      <primary>Popular URLs</primary>
    </indexterm>
    <para>The submenu 
    <guilabel>Popular URLs</guilabel>
    holds persistent the most popular visited &URL;s
    (local or remote). This submenu displays the top 15 popular
    URLs, sorted by ranking, so that the top &URL; is
    the most popular. This is easy for when you need to visit
    &URL;s often, but do not want to create
    <link linkend="bookman">Bookmarks</link>, it serves as a temporary bookmark
    list for the most visited links. 
    Quicksearch in <guilabel>Popular URLs</guilabel> is a fast way to
    browse/select the popular &URL;s: 
    <itemizedlist>
      <listitem>
        <para>Open the 
        <guilabel>Popular URLs</guilabel>
        or use 
        <keycombo action="simul">&Ctrl;
        <keycap>Z</keycap></keycombo></para>
      </listitem>
      <listitem>
        <para>Type a few letters to narrow the search</para>
      </listitem>
      <listitem>
        <para>Press &Enter; (you will go to the &URL; from
        list)</para>
      </listitem>
    </itemizedlist></para>
  </sect2>
  <sect2 id="permanent_bookmarks">
    <title>Permanent bookmarks</title>
    <para>These are hardcoded bookmarks to the top bookmark menu;
    there is no need for them to be saved to the file. With the
    <link linkend="context-menu">Context Menu</link> you can enable/disable these
    permanent bookmarks. The following permanent bookmarks are
    available: 
    <itemizedlist>
      <listitem>
        <para>
        <guilabel>Trash bin</guilabel> uses &plasma;'s 
        <filename>trash:/</filename> protocol.</para>
      </listitem>
      <listitem>
        <para>
        <guilabel>Local Network</guilabel> uses &plasma;'s 
        <filename>remote:/</filename> protocol.</para>
      </listitem>
      <listitem>
        <para>
        <guilabel>Virtual Filesystem</guilabel> <link linkend="vfs">Virtual file systems (VFS)</link>
        
        <filename>virt:/</filename> is not a virtual folder, but a
        container for &URL;s from different file
        systems. It is used for &eg; the 
        <guilabel>Feed to Listbox</guilabel> feature of the search
        module and the synchronizer. The location toolbar will
        display &eg;
        <filename>virt:/Search results 1</filename> or 
        <filename>virt:/Synchronise results 1</filename>.</para>
      </listitem>
      <listitem id="jump_back">
        <para>
        <guilabel>Jump back</guilabel> or 
        <keycombo action="simul">&Ctrl;
        <keycap>J</keycap></keycombo> brings you back to your
        starting position when you did create a new tab in the
        panel window. This feature is very handy if you go deep
        into a directory tree, then you can return with one action
        to the starting point. With 
        <guilabel>Set jump back point here</guilabel> or 
        <keycombo action="simul">
        &Ctrl;&Shift;
        <keycap>J</keycap></keycombo> sets the current directory as
        a jump back point.</para>
      </listitem>
    </itemizedlist></para>
  </sect2>
  <sect2 id="manage_bookmarks">
    <title>Manage bookmarks</title>
    <para>To edit and organize your bookmarks, by clicking the 
    <guibutton>BookMan II</guibutton> button and selecting the 
    <guimenuitem>Manage Bookmarks</guimenuitem>,
    <application>KeditBookmarks</application> will be displayed. This is where
    you can edit/remove and rearrange the bookmarks.
    <application>KeditBookmarks</application> is a
    bookmark editor for &konqueror;,
    &krusader; and other applications, which use the
    <ulink url="http://grail.sourceforge.net/info/xbel.html">XBEL standard</ulink> for the bookmark format. The
    bookmarks are stored in 
    <filename>
    ~/.local/share/krusader/krbookmarks.xml</filename>.</para>
    <note>
        <para>
            The default folder for the bookmarks file <filename>krusader/krbookmarks.xml</filename> is <filename class="directory">~/.local/share</filename>. You can determine the needed folder in your system using the <userinput>qtpaths --paths GenericDataLocation</userinput> command in terminal.
        </para>
        <para>
            This local file exists only if you have edited &krusader; bookmarks. It will be created after the first run of <application>KeditBookmarks</application> from &krusader;.
        </para>
        <para>
            The default system bookmarks are stored in the <filename>kfileplaces/bookmarks.xml</filename> file in the directory which can be determined using the <userinput>qtpaths --paths GenericDataLocation</userinput> command.
        </para>
    </note>
    <para>
    <application>KeditBookmarks</application> is easy to use, however, if you
    need more information, please read the
    <ulink url="help:/keditbookmarks/index.html">KeditBookmarks handbook</ulink>.</para>
    <figure id="screenshot-bookmanedit" float="1">
      <title><application>KeditBookmarks</application> Bookmark Manager</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="bookmanedit.png"></imagedata>
        </imageobject>
        <textobject>
          <phrase><application>KeditBookmarks</application> Bookmark
          Manager</phrase>
        </textobject>
      </mediaobject>
    </figure>
  </sect2>
  <sect2 id="bookmark_buttons">
    <title>Bookmarks as action buttons on the Toolbar</title>
    <para>Bookmarks can be placed as buttons on the
    <link linkend="mainwindow">Main Toolbar</link> or the
    <link linkend="actions_toolbar">Actions Toolbar</link>. You can even make a
    key-binding for them: 
    <itemizedlist>
      <listitem>
        <para>Create your <link linkend="bookman">Bookmarks</link>.</para>
      </listitem>
      <listitem>
        <para>If you want, create keybindings for the bookmarks in
        the <link linkend="key_bindings">Configure Shortcuts</link> window (<menuchoice><guimenu>Settings</guimenu> 
      <guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice>).</para>
      </listitem>
      <listitem>
        <para>Add your bookmarks as action buttons on the
        <link linkend="mainwindow">Main Toolbar</link> or the
        <link linkend="actions_toolbar">Actions Toolbar</link> with the 
        <guilabel>Configure Toolbars</guilabel> window 
        (<menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure Toolbars...</guimenuitem></menuchoice>).</para>
      </listitem>
    </itemizedlist></para>
  </sect2>
</sect1>
