recoll / Code / Diff of /src/doc/user/usermanual.xml

Diff of /src/doc/user/usermanual.xml [c897a0] .. [030e57]

Switch to unified view


...
          it has a way to read. This is sometimes not desirable, and
          there are ways to either exclude some types, or on the
          contrary to define a positive list of types to be
          indexed. In the latter case, any type not in the list will
          be ignored.</para>

        <para>Excluding types can be done by adding wildcard name
          patterns to the <literal>skippedNames</literal> list, which
          can be done from the GUI Index configuration menu. For
          versions 1.20 and later, you can alternatively set the
          <literal>excludedmimetypes</literal> list in the
          configuration file. This can be redefined for
          subdirectories.</para>



        <para>You can also define an exclusive list of MIME types to be indexed (no others will be indexed), by settting



            the <literal>indexedmimetypes</literal> configuration
            variable. Example:<programlisting>
indexedmimetypes = text/html application/pdf
          </programlisting>
          It is possible to redefine this parameter for
...
[/path/to/my/dir]
indexedmimetypes = application/pdf
          </programlisting>
          (When using sections like this, don't forget that they remain
          in effect until the end of the file or another section
          indicator).</para>

          <para>In order to set <literal>excludedmimetypes</literal>
          or <literal>indexedmimetypes</literal>, you need to edit the
          <link linkend="RCL.INSTALL.CONFIG.RECOLLCONF">main
            configuration file
            (<filename>recoll.conf</filename>)</link>. I used to have
            a bogus reason for this, but the really true truth is that
            I was too lazy to extend the GUI for these relatively
            rarely used parameters.
        </para>




      </sect2>

...
          attributes, which are handled as such by &RCL;:
        <variablelist>
          <varlistentry>
            <term>mime_type</term>
            <listitem><para>If set, this overrides any other
                determination of the file MIME type.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>charset</term>
            <listitem>If set, this defines the file character set
              (mostly useful for plain text files).</listitem>
...
       types (there is a short list of exceptions, see further). If you
       prefer to completely customize the choice of applications, you can
       uncheck the <guilabel>Use desktop preferences</guilabel> option in
       the GUI preferences dialog, and click the <guilabel>Choose editor
       applications</guilabel> button to adjust the predefined &RCL;
       choices. The tool accepts multiple selections of MIME types (e.g. to
       set up the editor for the dozens of office file types).</para>

        <para>Even when <guilabel>Use desktop preferences</guilabel> is
        checked, there is a small list of exceptions, for MIME types where
        the &RCL; choice should override the desktop one. These are
        applications which are well integrated with &RCL;, especially
        <application>evince</application> for viewing PDF and Postscript
        files because of its support for opening the document at a specific
        page and passing a search string as an argument. Of course, you can
...
          for, and permits specifying multiple clauses which are combined
          to build the search.</para>
         </listitem> 

      <listitem><para>The second tab lets filter the results according
          to file size, date of modification, MIME type, or
          location.</para>
         </listitem>
     
      </orderedlist>

...
            <literal>g/G</literal>, <literal>t/T</literal> for 1E3, 1E6,
            1E9, 1E12 respectively.</para>
      </listitem>

      <listitem>   
      <para>The next section allows filtering the results by their MIME
            types, or MIME categories (ie: media/text/message/etc.).</para>
          <para>You can transfer the types between two boxes, to define
            which will be included or excluded by the search.</para>
          <para>The state of the file type selection can be saved as
            the default (the file type filter will not be activated at
            program start-up, but the lists will be in the restored
...
            in term use your desktop preferences to choose an appropriate
            application.</para>
           </listitem>

            <listitem><para><guilabel>Exceptions</guilabel>: when using the
            desktop preferences for opening documents, these are MIME types
            that will still be opened according to &RCL; preferences. This
            is useful for passing parameters like page numbers or search
            strings to applications that support them
            (e.g. <application>evince</application>). This cannot be done
            with <command>xdg-open</command> which only supports passing
...
            <formalpara><title>%A</title><para>Abstract</para></formalpara>
          </listitem>
          <listitem><formalpara><title>%D</title><para>Date</para></formalpara>
          </listitem>
          <listitem><formalpara><title>%I</title><para>Icon image
            name. This is normally determined from the MIME type. The
            associations are defined inside the 
            <link linkend="RCL.INSTALL.CONFIG.MIMECONF">
              <filename>mimeconf</filename> configuration file</link>. 
            If a thumbnail for the file is found at
            the standard Freedesktop location, this will be displayed
...
          any)</para></formalpara> 
          </listitem>
          <listitem><formalpara><title>%L</title><para>Precooked Preview,
            Edit, and possibly Snippets links</para></formalpara> 
          </listitem>
          <listitem><formalpara><title>%M</title><para>MIME
                  type</para></formalpara> 
          </listitem>
          <listitem><formalpara><title>%N</title><para>result Number inside
            the result page</para></formalpara> 
          </listitem>
...
        p2y).</para> 
           </listitem>

        <listitem><para><literal>mime</literal> or
            <literal>format</literal> for specifying the
            MIME type. This one is quite special because you can specify
            several values which will be OR'ed (the normal default for the
            language is AND). Ex: <literal>mime:text/plain
              mime:text/html</literal>. Specifying an explicit boolean
            operator before a
            <literal>mime</literal> specification is not supported and
...
            example.</para> 
           </listitem>

        <listitem><para><literal>type</literal> or
            <literal>rclcat</literal> for specifying the category (as in
            text/media/presentation/etc.). The classification of MIME
            types in categories is defined in the &RCL; configuration
            (<filename>mimeconf</filename>), and can be modified or
            extended. The default category names are those which permit
            filtering results in the main GUI screen. Categories are OR'ed
            like MIME types above. This can't be negated with
            <literal>-</literal> either.</para>
           </listitem>

         </itemizedlist>

...

      <sect2 id="RCL.PROGRAM.FILTERS.ASSOCIATION">
        <title>Telling &RCL; about the handler</title>

      <para>There are two elements that link a file to the handler which
      should process it: the association of file to MIME type and the
      association of a MIME type with a handler.</para>

      <para>The association of files to MIME types is mostly based on
        name suffixes. The types are defined inside the
        <link linkend="RCL.INSTALL.CONFIG.MIMEMAP">
        <filename>mimemap</filename> file</link>. Example:
<programlisting>

.doc = application/msword
</programlisting>
       If no suffix association is found for the file name, &RCL; will try
       to execute the <command>file -i</command> command to determine a
       MIME type.</para>

      <para>The association of file types to handlers is performed in
      the <link linkend="RCL.INSTALL.CONFIG.MIMECONF">
      <filename>mimeconf</filename> file</link>. A sample will probably be
      of better help than a long explanation:</para>
...
          </varlistentry>

          <varlistentry><term><varname>indexedmimetypes</varname></term>
            <listitem><para>&RCL; normally indexes any file which it
            knows how to read. This list lets you restrict the indexed
            MIME types to what you specify. If the variable is
            unspecified or the list empty (the default), all supported
            types are processed. Can be redefined for subdirectories.</para>
            </listitem>
          </varlistentry>

          <varlistentry><term><varname>excludedmimetypes</varname></term>
            <listitem><para> This list lets you exclude some MIME types from
            indexing. Can be redefined for subdirectories.</para>
            </listitem>
          </varlistentry>

          <varlistentry><term><varname>compressedfilemaxkbs</varname></term>
            <listitem><para>Size limit for compressed (.gz or .bz2)
...

          <varlistentry><term><varname>indexallfilenames</varname></term>
            <listitem><para>&RCL; indexes file names in a special
            section of the database to allow specific file names
            searches using wild cards. This parameter decides if 
            file name indexing is performed only for files with MIME
            types that would qualify them for full text indexing, or
            for all files inside the selected subtrees, independently of
            MIME type.</para>
            </listitem>
          </varlistentry>

          <varlistentry><term><varname>usesystemfilecommand</varname></term>
            <listitem><para>Decide if we use the
            <command>file</command> <option>-i</option> system command
            as a final step for determining the MIME type for a file
            (the main procedure uses suffix associations as defined in
            the <filename>mimemap</filename> file). This can be useful
            for files with suffix-less names, but it will also cause
            the indexing of many bogus "text" files.</para>
            </listitem> 
...

      <sect2 id="RCL.INSTALL.CONFIG.MIMEMAP">
        <title>The mimemap file</title>

        <para><filename>mimemap</filename> specifies the
        file name extension to MIME type mappings.</para> 

        <para>For file names without an extension, or with an unknown
        one, the system's <command>file</command> <option>-i</option> 
    command will be
        executed to determine the MIME type (this can be switched off
        inside the main configuration file).</para>

        <para>The mappings can be specified on a per-subtree basis,
        which may be useful in some cases. Example:
        <application>gaim</application> logs have a
...

      <sect2 id="RCL.INSTALL.CONFIG.MIMECONF">
        <title>The mimeconf file</title>

        <para><filename>mimeconf</filename> specifies how the
         different MIME types are handled for indexing, and which icons
         are displayed in the <command>recoll</command> result lists.</para>

        <para>Changing the parameters in the [index] section is
         probably not a good idea except if you are a &RCL;
         developer.</para> 
...
        <filename>mimeview</filename> entries will be ignored except the
        one labelled <literal>application/x-all</literal> (which is set to
        use <command>xdg-open</command> by default).</para>

        <para>In this case, the <literal>xallexcepts</literal> top level
          variable defines a list of MIME type exceptions which
          will be processed according to the local entries instead of being
          passed to the desktop. This is so that specific &RCL; options
          such as a page number or a search string can be passed to
          applications that support them, such as the
          <application>evince</application> viewer.</para>
...
          file.</para>

        <para>All viewer definition entries must be placed under a
          <literal>[view]</literal> section.</para>

    <para>The keys in the file are normally MIME types. You can add an
      application tag to specialize the choice for an area of the
      filesystem (using a <varname>localfields</varname> specification
      in <filename>mimeconf</filename>). The syntax for the key is 
<replaceable>mimetype</replaceable><literal>|</literal><replaceable>tag</replaceable></para>

        <para>The <varname>nouncompforviewmts</varname> entry, (placed at
        the top level, outside of the <literal>[view]</literal> section),
        holds a list of MIME types that should not be uncompressed before
        starting the viewer (if they are found compressed, ie:
        <replaceable>mydoc.doc.gz</replaceable>).</para>

        <para>The right side of each assignment holds a command to be
        executed for opening the file. The following substitutions are
...
              extract the subdocument, expecting the called application
              (possibly a script) to be able to handle it.</para></formalpara>
          </listitem>

          <listitem><formalpara><title>%M</title>
              <para>MIME type</para></formalpara> 
          </listitem>

          <listitem><formalpara><title>%p</title>
              <para>Page index. Only significant for a subset of document
              types, currently only PDF, Postscript and DVI files. Can be
...
            <listitem><para>In <filename>$RECOLL_CONFDIR/mimemap</filename>
        (typically <filename>~/.recoll/mimemap</filename>), add the
        following line:<programlisting>
.blob = application/x-blobapp
</programlisting>
        Note that the MIME type is made up here, and you could
        call it <replaceable>diesel/oil</replaceable> just the
        same.</para>
            </listitem>
            <listitem><para>In <filename>$RECOLL_CONFDIR/mimeview</filename>
        under the <literal>[view]</literal> section, add:</para>
...
              it liked URLs better.</para>
            </listitem>
          </itemizedlist>

          <para>If you just wanted to change the application used by
            &RCL; to display a MIME type which it already knows, you
            would just need to edit <filename>mimeview</filename>. The
            entries you add in your personal file override those in the
            central configuration, which you do not need to
            alter. <filename>mimeview</filename> can also be modified
            from the Gui.</para>
...
        files inside the result lists. Icons are normally 64x64
        pixels PNG files which live in
        <filename>/usr/[local/]share/recoll/images</filename>.</para>
            </listitem>
            <listitem><para>Under the <literal>[categories]</literal>
        section, you should add the MIME type where it makes sense
        (you can also create a category). Categories may be used
        for filtering in advanced search.</para>
            </listitem>
          </itemizedlist>
