recoll.conf

package: recoll

title: recoll.conf(5)

text:
# recoll.conf(5)

## NAME
recoll.conf - main personal configuration file for Recoll

## DESCRIPTION
This file defines the index configuration for the Recoll full-text search system.

The system-wide configuration file is normally located inside /usr/[local]/share/recoll/examples. Any parameter set in the common file may be overridden by setting it in the personal configuration file, by default: $HOME/.recoll/recoll.conf

Please note while I try to keep this manual page reasonably up to date, it will frequently lag the current state of the software. The best source of information about the configuration are the comments in the system-wide configuration file or the user manual which you can access from the recoll GUI help menu or on the recoll web site.

A short extract of the file might look as follows:

```
# Space-separated list of directories to index.
topdirs =  ~/docs /usr/share/doc
[~/somedirectory-with-utf8-txt-files]
defaultcharset = utf-8

```

There are three kinds of lines:

- Comment or empty

- Parameter affectation

- Section definition

Empty lines or lines beginning with # are ignored.

Affectation lines are in the form 'name = value'.

Section lines allow redefining a parameter for a directory subtree. Some of the parameters used for indexing are looked up hierarchically from the more to the less specific. Not all parameters can be meaningfully redefined, this is specified for each in the next section.

The tilde character (~) is expanded in file names to the name of the user's home directory.

Where values are lists, white space is used for separation, and elements with embedded spaces can be quoted with double-quotes.

## OPTIONS
topdirs = string

Space-separated list of files or directories to recursively index. Default to ~ (indexes $HOME). You can use symbolic links in the list, they will be followed, independently of the value of the followLinks variable.

monitordirs = string

Space-separated list of files or directories to monitor for updates. When running the real-time indexer, this allows monitoring only a subset of the whole indexed area. The elements must be included in the tree defined by the 'topdirs' members.

skippedNames = string

Files and directories which should be ignored. White space separated list of wildcard patterns (simple ones, not paths, must contain no / ), which will be tested against file and directory names. The list in the default configuration does not exclude hidden directories (names beginning with a dot), which means that it may index quite a few things that you do not want. On the other hand, email user agents like Thunderbird usually store messages in hidden directories, and you probably want this indexed. One possible solution is to have ".*" in "skippedNames", and add things like "~/.thunderbird" "~/.evolution" to "topdirs". Not even the file names are indexed for patterns in this list, see the "noContentSuffixes" variable for an alternative approach which indexes the file names. Can be redefined for any subtree.

skippedNames- = string

List of name endings to remove from the default skippedNames list.

skippedNames+ = string

List of name endings to add to the default skippedNames list.

onlyNames = string

Regular file name filter patterns If this is set, only the file names not in skippedNames and matching one of the patterns will be considered for indexing. Can be redefined per subtree. Does not apply to directories.

noContentSuffixes = string

List of name endings (not necessarily dot-separated suffixes) for which we don't try MIME type identification, and don't uncompress or index content. Only the names will be indexed. This complements the now obsoleted recoll_noindex list from the mimemap file, which will go away in a future release (the move from mimemap to recoll.conf allows editing the list through the GUI). This is different from skippedNames because these are name ending matches only (not wildcard patterns), and the file name itself gets indexed normally. This can be redefined for subdirectories.

noContentSuffixes- = string

List of name endings to remove from the default noContentSuffixes list.

noContentSuffixes+ = string

List of name endings to add to the default noContentSuffixes list.

skippedPaths = string

Absolute paths we should not go into. Space-separated list of wildcard expressions for absolute filesystem paths. Must be defined at the top level of the configuration file, not in a subsection. Can contain files and directories. The database and configuration directories will automatically be added. The expressions are matched using 'fnmatch(3)' with the FNM_PATHNAME flag set by default. This means that '/' characters must be matched explicitly. You can set 'skippedPathsFnmPathname' to 0 to disable the use of FNM_PATHNAME (meaning that '/*/dir3' will match '/dir1/dir2/dir3'). The default value contains the usual mount point for removable media to remind you that it is a bad idea to have Recoll work on these (esp. with the monitor: media gets indexed on mount, all data gets erased on unmount). Explicitly adding '/media/xxx' to the 'topdirs' variable will override this.

skippedPathsFnmPathname = bool

Set to 0 to override use of FNM_PATHNAME for matching skipped paths.

nowalkfn = string

File name which will cause its parent directory to be skipped. Any directory containing a file with this name will be skipped as if it was part of the skippedPaths list. Ex: .recoll-noindex

daemSkippedPaths = string

skippedPaths equivalent specific to real time indexing. This enables having parts of the tree which are initially indexed but not monitored. If daemSkippedPaths is not set, the daemon uses skippedPaths.

zipUseSkippedNames = bool

Use skippedNames inside Zip archives. Fetched directly by the rclzip.py handler. Skip the patterns defined by skippedNames inside Zip archives. Can be redefined for subdirectories. See https://www.recoll.org/faqsandhowtos/FilteringOutZipArchiveMembers.html

zipSkippedNames = string

Space-separated list of wildcard expressions for names that should be ignored inside zip archives. This is used directly by the zip handler. If zipUseSkippedNames is not set, zipSkippedNames defines the patterns to be skipped inside archives. If zipUseSkippedNames is set, the two lists are concatenated and used. Can be redefined for subdirectories. See https://www.recoll.org/faqsandhowtos/FilteringOutZipArchiveMembers.html

followLinks = bool

Follow symbolic links during indexing. The default is to ignore symbolic links to avoid multiple indexing of linked files. No effort is made to avoid duplication when this option is set to true. This option can be set individually for each of the 'topdirs' members by using sections. It can not be changed below the 'topdirs' level. Links in the 'topdirs' list itself are always followed.

indexedmimetypes = string

Restrictive list of indexed mime types. Normally not set (in which case all supported types are indexed). If it is set, only the types from the list will have their contents indexed. The names will be indexed anyway if indexallfilenames is set (default). MIME type names should be taken from the mimemap file (the values may be different from xdg-mime or file -i output in some cases). Can be redefined for subtrees.

excludedmimetypes = string

List of excluded MIME types. Lets you exclude some types from indexing. MIME type names should be taken from the mimemap file (the values may be different from xdg-mime or file -i output in some cases) Can be redefined for subtrees.

nomd5types = string

Don't compute md5 for these types. md5 checksums are used only for deduplicating results, and can be very expensive to compute on multimedia or other big files. This list lets you turn off md5 computation for selected types. It is global (no redefinition for subtrees). At the moment, it only has an effect for external handlers (exec and execm). The file types can be specified by listing either MIME types (e.g. audio/mpeg) or handler names (e.g. rclaudio.py).

compressedfilemaxkbs = int

Size limit for compressed files. We need to decompress these in a temporary directory for identification, which can be wasteful in some cases. Limit the waste. Negative means no limit. 0 results in no processing of any compressed file. Default 50 MB.

textfilemaxmbs = int

Size limit for text files. Mostly for skipping monster logs. Default 20 MB.

indexallfilenames = bool

Index the file names of unprocessed files Index the names of files the contents of which we don't index because of an excluded or unsupported MIME type.

usesystemfilecommand = bool

Use a system command for file MIME type guessing as a final step in file type identification This is generally useful, but will usually cause the indexing of many bogus 'text' files. See 'systemfilecommand' for the command used.

systemfilecommand = string

Command used to guess MIME types if the internal methods fails This should be a "file -i" workalike. The file path will be added as a last parameter to the command line. "xdg-mime" works better than the traditional "file" command, and is now the configured default (with a hard-coded fallback to "file")

processwebqueue = bool

Decide if we process the Web queue. The queue is a directory where the Recoll Web browser plugins create the copies of visited pages.

textfilepagekbs = int

Page size for text files. If this is set, text/plain files will be divided into documents of approximately this size. Will reduce memory usage at index time and help with loading data in the preview window at query time. Particularly useful with very big files, such as application or system logs. Also see textfilemaxmbs and compressedfilemaxkbs.

membermaxkbs = int

Size limit for archive members. This is passed to the filters in the environment as RECOLL_FILTER_MAXMEMBERKB.

indexStripChars = bool

Decide if we store character case and diacritics in the index. If we do, searches sensitive to case and diacritics can be performed, but the index will be bigger, and some marginal weirdness may sometimes occur. The default is a stripped index. When using multiple indexes for a search, this parameter must be defined identically for all. Changing the value implies an index reset.

indexStoreDocText = bool

Decide if we store the documents' text content in the index. Storing the text allows extracting snippets from it at query time, instead of building them from index position data. Newer Xapian index formats have rendered our use of positions list unacceptably slow in some cases. The last Xapian index format with good performance for the old method is Chert, which is default for 1.2, still supported but not default in 1.4 and will be dropped in 1.6. The stored document text is translated from its original format to UTF-8 plain text, but not stripped of upper-case, diacritics, or punctuation signs. Storing it increases the index size by 10-20% typically, but also allows for nicer snippets, so it may be worth enabling it even if not strictly needed for performance if you can afford the space. The variable only has an effect when creating an index, meaning that the xapiandb directory must not exist yet. Its exact effect depends on the Xapian version. For Xapian 1.4, if the variable is set to 0, the Chert format will be used, and the text will not be stored. If the variable is 1, Glass will be used, and the text stored. For Xapian 1.2, and for versions after 1.5 and newer, the index format is always the default, but the variable controls if the text is stored or not, and the abstract generation method. With Xapian 1.5 and later, and the variable set to 0, abstract generation may be very slow, but this setting may still be useful to save space if you do not use abstract generation at all.

nonumbers = bool

Decides if terms will be generated for numbers. For example "123", "1.5e6", 192.168.1.4, would not be indexed if nonumbers is set ("value123" would still be). Numbers are often quite interesting to search for, and this should probably not be set except for special situations, ie, scientific documents with huge amounts of numbers in them, where setting nonumbers will reduce the index size. This can only be set for a whole index, not for a subtree.

dehyphenate = bool

Determines if we index 'coworker' also when the input is 'co-worker'. This is new in version 1.22, and on by default. Setting the variable to off allows restoring the previous behaviour.

backslashasletter = bool

Process backslash as normal letter. This may make sense for people wanting to index TeX commands as such but is not of much general use.

underscoreasletter = bool

Process underscore as normal letter. This makes sense in so many cases that one wonders if it should not be the default.

maxtermlength = int

Maximum term length. Words longer than this will be discarded. The default is 40 and used to be hard-coded, but it can now be adjusted. You need an index reset if you change the value.

nocjk = bool

Decides if specific East Asian (Chinese Korean Japanese) characters/word splitting is turned off. This will save a small amount of CPU if you have no CJK documents. If your document base does include such text but you are not interested in searching it, setting nocjk may be a significant time and space saver.

cjkngramlen = int

This lets you adjust the size of n-grams used for indexing CJK text. The default value of 2 is probably appropriate in most cases. A value of 3 would allow more precision and efficiency on longer words, but the index will be approximately twice as large.

indexstemminglanguages = string

Languages for which to create stemming expansion data. Stemmer names can be found by executing 'recollindex -l', or this can also be set from a list in the GUI. The values are full language names, e.g. english, french...

defaultcharset = string

Default character set. This is used for files which do not contain a character set definition (e.g.: text/plain). Values found inside files, e.g. a 'charset' tag in HTML documents, will override it. If this is not set, the default character set is the one defined by the NLS environment ($LC_ALL, $LC_CTYPE, $LANG), or ultimately iso-8859-1 (cp-1252 in fact). If for some reason you want a general default which does not match your LANG and is not 8859-1, use this variable. This can be redefined for any sub-directory.

unac_except_trans = string

A list of characters, encoded in UTF-8, which should be handled specially when converting text to unaccented lowercase. For example, in Swedish, the letter a with diaeresis has full alphabet citizenship and should not be turned into an a. Each element in the space-separated list has the special character as first element and the translation following. The handling of both the lowercase and upper-case versions of a character should be specified, as appartenance to the list will turn-off both standard accent and case processing. The value is global and affects both indexing and querying. Examples:

Swedish:

unac_except_trans = ää Ää öö Öö üü Üü ßss œoe Œoe æae Æae ﬀff ﬁfi ﬂfl åå Åå

German:

unac_except_trans = ää Ää öö Öö üü Üü ßss œoe Œoe æae Æae ﬀff ﬁfi ﬂfl

French: you probably want to decompose oe and ae and nobody would type a German ß

unac_except_trans = ßss œoe Œoe æae Æae ﬀff ﬁfi ﬂfl

The default for all until someone protests follows. These decompositions are not performed by unac, but it is unlikely that someone would type the composed forms in a search.

unac_except_trans = ßss œoe Œoe æae Æae ﬀff ﬁfi ﬂfl

maildefcharset = string

Overrides the default character set for email messages which don't specify one. This is mainly useful for readpst (libpst) dumps, which are utf-8 but do not say so.

localfields = string

Set fields on all files (usually of a specific fs area). Syntax is the usual: name = value ; attr1 = val1 ; [...] value is empty so this needs an initial semi-colon. This is useful, e.g., for setting the rclaptg field for application selection inside mimeview.

testmodifusemtime = bool

Use mtime instead of ctime to test if a file has been modified. The time is used in addition to the size, which is always used. Setting this can reduce re-indexing on systems where extended attributes are used (by some other application), but not indexed, because changing extended attributes only affects ctime. Notes: - This may prevent detection of change in some marginal file rename cases (the target would need to have the same size and mtime). - You should probably also set noxattrfields to 1 in this case, except if you still prefer to perform xattr indexing, for example if the local file update pattern makes it of value (as in general, there is a risk for pure extended attributes updates without file modification to go undetected). Perform a full index reset after changing this.

noxattrfields = bool

Disable extended attributes conversion to metadata fields. This probably needs to be set if testmodifusemtime is set.

metadatacmds = string

Define commands to gather external metadata, e.g. tmsu tags. There can be several entries, separated by semi-colons, each defining which field name the data goes into and the command to use. Don't forget the initial semi-colon. All the field names must be different. You can use aliases in the "field" file if necessary. As a not too pretty hack conceded to convenience, any field name beginning with "rclmulti" will be taken as an indication that the command returns multiple field values inside a text blob formatted as a recoll configuration file ("fieldname = fieldvalue" lines). The rclmultixx name will be ignored, and field names and values will be parsed from the data. Example: metadatacmds = ; tags = tmsu tags %f; rclmulti1 = cmdOutputsConf %f

cachedir = dfn

Top directory for Recoll data. Recoll data directories are normally located relative to the configuration directory (e.g. ~/.recoll/xapiandb, ~/.recoll/mboxcache). If 'cachedir' is set, the directories are stored under the specified value instead (e.g. if cachedir is ~/.cache/recoll, the default dbdir would be ~/.cache/recoll/xapiandb). This affects dbdir, webcachedir, mboxcachedir, aspellDicDir, which can still be individually specified to override cachedir. Note that if you have multiple configurations, each must have a different cachedir, there is no automatic computation of a subpath under cachedir.

maxfsoccuppc = int

Maximum file system occupation over which we stop indexing. The value is a percentage, corresponding to what the "Capacity" df output column shows. The default value is 0, meaning no checking.

dbdir = dfn

Xapian database directory location. This will be created on first indexing. If the value is not an absolute path, it will be interpreted as relative to cachedir if set, or the configuration directory (-c argument or $RECOLL_CONFDIR). If nothing is specified, the default is then ~/.recoll/xapiandb/

idxstatusfile = fn

Name of the scratch file where the indexer process updates its status. Default: idxstatus.txt inside the configuration directory.

mboxcachedir = dfn

Directory location for storing mbox message offsets cache files. This is normally 'mboxcache' under cachedir if set, or else under the configuration directory, but it may be useful to share a directory between different configurations.

mboxcacheminmbs = int

Minimum mbox file size over which we cache the offsets. There is really no sense in caching offsets for small files. The default is 5 MB.

mboxmaxmsgmbs = int

Maximum mbox member message size in megabytes. Size over which we assume that the mbox format is bad or we misinterpreted it, at which point we just stop processing the file.

webcachedir = dfn

Directory where we store the archived web pages. This is only used by the web history indexing code Default: cachedir/webcache if cachedir is set, else $RECOLL_CONFDIR/webcache

webcachemaxmbs = int

Maximum size in MB of the Web archive. This is only used by the web history indexing code. Default: 40 MB. Reducing the size will not physically truncate the file.

webqueuedir = fn

The path to the Web indexing queue. This used to be hard-coded in the old plugin as ~/.recollweb/ToIndex so there would be no need or possibility to change it, but the WebExtensions plugin now downloads the files to the user Downloads directory, and a script moves them to webqueuedir. The script reads this value from the config so it has become possible to change it.

webdownloadsdir = fn

The path to browser downloads directory. This is where the new browser add-on extension has to create the files. They are then moved by a script to webqueuedir.

aspellDicDir = dfn

Aspell dictionary storage directory location. The aspell dictionary (aspdict.(lang).rws) is normally stored in the directory specified by cachedir if set, or under the configuration directory.

filtersdir = dfn

Directory location for executable input handlers. If RECOLL_FILTERSDIR is set in the environment, we use it instead. Defaults to $prefix/share/recoll/filters. Can be redefined for subdirectories.

iconsdir = dfn

Directory location for icons. The only reason to change this would be if you want to change the icons displayed in the result list. Defaults to $prefix/share/recoll/images

idxflushmb = int

Threshold (megabytes of new data) where we flush from memory to disk index. Setting this allows some control over memory usage by the indexer process. A value of 0 means no explicit flushing, which lets Xapian perform its own thing, meaning flushing every $XAPIAN_FLUSH_THRESHOLD documents created, modified or deleted: as memory usage depends on average document size, not only document count, the Xapian approach is is not very useful, and you should let Recoll manage the flushes. The program compiled value is 0. The configured default value (from this file) is now 50 MB, and should be ok in many cases. You can set it as low as 10 to conserve memory, but if you are looking for maximum speed, you may want to experiment with values between 20 and 200. In my experience, values beyond this are always counterproductive. If you find otherwise, please drop me a note.

filtermaxseconds = int

Maximum external filter execution time in seconds. Default 1200 (20mn). Set to 0 for no limit. This is mainly to avoid infinite loops in postscript files (loop.ps)

filtermaxmbytes = int

Maximum virtual memory space for filter processes (setrlimit(RLIMIT_AS)), in megabytes. Note that this includes any mapped libs (there is no reliable Linux way to limit the data space only), so we need to be a bit generous here. Anything over 2000 will be ignored on 32 bits machines. The previous default value of 2000 would prevent java pdftk to work when executed from Python rclpdf.py.

thrQSizes = string

Stage input queues configuration. There are three internal queues in the indexing pipeline stages (file data extraction, terms generation, index update). This parameter defines the queue depths for each stage (three integer values). If a value of -1 is given for a given stage, no queue is used, and the thread will go on performing the next stage. In practise, deep queues have not been shown to increase performance. Default: a value of 0 for the first queue tells Recoll to perform autoconfiguration based on the detected number of CPUs (no need for the two other values in this case). Use thrQSizes = -1 -1 -1 to disable multithreading entirely.

thrTCounts = string

Number of threads used for each indexing stage. The three stages are: file data extraction, terms generation, index update). The use of the counts is also controlled by some special values in thrQSizes: if the first queue depth is 0, all counts are ignored (autoconfigured); if a value of -1 is used for a queue depth, the corresponding thread count is ignored. It makes no sense to use a value other than 1 for the last stage because updating the Xapian index is necessarily single-threaded (and protected by a mutex).

loglevel = int

Log file verbosity 1-6. A value of 2 will print only errors and warnings. 3 will print information like document updates, 4 is quite verbose and 6 very verbose.

logfilename = fn

Log file destination. Use 'stderr' (default) to write to the console.

idxloglevel = int

Override loglevel for the indexer.

idxlogfilename = fn

Override logfilename for the indexer.

daemloglevel = int

Override loglevel for the indexer in real time mode. The default is to use the idx... values if set, else the log... values.

daemlogfilename = fn

Override logfilename for the indexer in real time mode. The default is to use the idx... values if set, else the log... values.

pyloglevel = int

Override loglevel for the python module.

pylogfilename = fn

Override logfilename for the python module.

orgidxconfdir = dfn

Original location of the configuration directory. This is used exclusively for movable datasets. Locating the configuration directory inside the directory tree makes it possible to provide automatic query time path translations once the data set has moved (for example, because it has been mounted on another location).

curidxconfdir = dfn

Current location of the configuration directory. Complement orgidxconfdir for movable datasets. This should be used if the configuration directory has been copied from the dataset to another location, either because the dataset is readonly and an r/w copy is desired, or for performance reasons. This records the original moved location before copy, to allow path translation computations. For example if a dataset originally indexed as '/home/me/mydata/config' has been mounted to '/media/me/mydata', and the GUI is running from a copied configuration, orgidxconfdir would be '/home/me/mydata/config', and curidxconfdir (as set in the copied configuration) would be '/media/me/mydata/config'.

idxrundir = dfn

Indexing process current directory. The input handlers sometimes leave temporary files in the current directory, so it makes sense to have recollindex chdir to some temporary directory. If the value is empty, the current directory is not changed. If the value is (literal) tmp, we use the temporary directory as set by the environment (RECOLL_TMPDIR else TMPDIR else /tmp). If the value is an absolute path to a directory, we go there.

checkneedretryindexscript = fn

Script used to heuristically check if we need to retry indexing files which previously failed. The default script checks the modified dates on /usr/bin and /usr/local/bin. A relative path will be looked up in the filters dirs, then in the path. Use an absolute path to do otherwise.

recollhelperpath = string

Additional places to search for helper executables. This is only used on Windows for now.

idxabsmlen = int

Length of abstracts we store while indexing. Recoll stores an abstract for each indexed file. The text can come from an actual 'abstract' section in the document or will just be the beginning of the document. It is stored in the index so that it can be displayed inside the result lists without decoding the original file. The idxabsmlen parameter defines the size of the stored abstract. The default value is 250 bytes. The search interface gives you the choice to display this stored text or a synthetic abstract built by extracting text around the search terms. If you always prefer the synthetic abstract, you can reduce this value and save a little space.

idxmetastoredlen = int

Truncation length of stored metadata fields. This does not affect indexing (the whole field is processed anyway), just the amount of data stored in the index for the purpose of displaying fields inside result lists or previews. The default value is 150 bytes which may be too low if you have custom fields.

idxtexttruncatelen = int

Truncation length for all document texts. Only index the beginning of documents. This is not recommended except if you are sure that the interesting keywords are at the top and have severe disk space issues.

aspellLanguage = string

Language definitions to use when creating the aspell dictionary. The value must match a set of aspell language definition files. You can type "aspell dicts" to see a list The default if this is not set is to use the NLS environment to guess the value. The values are the 2-letter language codes (e.g. 'en', 'fr'...)

aspellAddCreateParam = string

Additional option and parameter to aspell dictionary creation command. Some aspell packages may need an additional option (e.g. on Debian Jessie: --local-data-dir=/usr/lib/aspell). See Debian bug 772415.

aspellKeepStderr = bool

Set this to have a look at aspell dictionary creation errors. There are always many, so this is mostly for debugging.

noaspell = bool

Disable aspell use. The aspell dictionary generation takes time, and some combinations of aspell version, language, and local terms, result in aspell crashing, so it sometimes makes sense to just disable the thing.

monauxinterval = int

Auxiliary database update interval. The real time indexer only updates the auxiliary databases (stemdb, aspell) periodically, because it would be too costly to do it for every document change. The default period is one hour.

monixinterval = int

Minimum interval (seconds) between processings of the indexing queue. The real time indexer does not process each event when it comes in, but lets the queue accumulate, to diminish overhead and to aggregate multiple events affecting the same file. Default 30 S.

mondelaypatterns = string

Timing parameters for the real time indexing. Definitions for files which get a longer delay before reindexing is allowed. This is for fast-changing files, that should only be reindexed once in a while. A list of wildcardPattern:seconds pairs. The patterns are matched with fnmatch(pattern, path, 0) You can quote entries containing white space with double quotes (quote the whole entry, not the pattern). The default is empty. Example: mondelaypatterns = *.log:20 "*with spaces.*:30"

idxniceprio = int

"nice" process priority for the indexing processes. Default: 19 (lowest) Appeared with 1.26.5. Prior versions were fixed at 19.

monioniceclass = int

ionice class for the indexing process. Despite the misleading name, and on platforms where this is supported, this affects all indexing processes, not only the real time/monitoring ones. The default value is 3 (use lowest "Idle" priority).

monioniceclassdata = string

ionice class level parameter if the class supports it. The default is empty, as the default "Idle" class has no levels.

autodiacsens = bool

auto-trigger diacritics sensitivity (raw index only). IF the index is not stripped, decide if we automatically trigger diacritics sensitivity if the search term has accented characters (not in unac_except_trans). Else you need to use the query language and the "D" modifier to specify diacritics sensitivity. Default is no.

autocasesens = bool

auto-trigger case sensitivity (raw index only). IF the index is not stripped (see indexStripChars), decide if we automatically trigger character case sensitivity if the search term has upper-case characters in any but the first position. Else you need to use the query language and the "C" modifier to specify character-case sensitivity. Default is yes.

maxTermExpand = int

Maximum query expansion count for a single term (e.g.: when using wildcards). This only affects queries, not indexing. We used to not limit this at all (except for filenames where the limit was too low at 1000), but it is unreasonable with a big index. Default 10000.

maxXapianClauses = int

Maximum number of clauses we add to a single Xapian query. This only affects queries, not indexing. In some cases, the result of term expansion can be multiplicative, and we want to avoid eating all the memory. Default 50000.

snippetMaxPosWalk = int

Maximum number of positions we walk while populating a snippet for the result list. The default of 1,000,000 may be insufficient for very big documents, the consequence would be snippets with possibly meaning-altering missing words.

pdfocr = bool

Attempt OCR of PDF files with no text content. This can be defined in subdirectories. The default is off because OCR is so very slow.

pdfattach = bool

Enable PDF attachment extraction by executing pdftk (if available). This is normally disabled, because it does slow down PDF indexing a bit even if not one attachment is ever found.

pdfextrameta = string

Extract text from selected XMP metadata tags. This is a space-separated list of qualified XMP tag names. Each element can also include a translation to a Recoll field name, separated by a '|' character. If the second element is absent, the tag name is used as the Recoll field names. You will also need to add specifications to the "fields" file to direct processing of the extracted data.

pdfextrametafix = fn

Define name of XMP field editing script. This defines the name of a script to be loaded for editing XMP field values. The script should define a 'MetaFixer' class with a metafix() method which will be called with the qualified tag name and value of each selected field, for editing or erasing. A new instance is created for each document, so that the object can keep state for, e.g. eliminating duplicate values.

ocrprogs = string

OCR modules to try. The top OCR script will try to load the corresponding modules in order and use the first which reports being capable of performing OCR on the input file. Modules for tesseract (tesseract) and ABBYY FineReader (abbyy) are present in the standard distribution. For compatibility with the previous version, if this is not defined at all, the default value is "tesseract". Use an explicit empty value if needed. A value of "abbyy tesseract" will try everything.

ocrcachedir = dfn

Location for caching OCR data. The default if this is empty or undefined is to store the cached OCR data under $RECOLL_CONFDIR/ocrcache.

tesseractlang = string

Language to assume for tesseract OCR. Important for improving the OCR accuracy. This can also be set through the contents of a file in the currently processed directory. See the rclocrtesseract.py script. Example values: eng, fra... See the tesseract documentation.

tesseractcmd = fn

Path for the tesseract command. Do not quote. This is mostly useful on Windows, or for specifying a non-default tesseract command. E.g. on Windows. tesseractcmd = C:/Program Files (x86)/Tesseract-OCR/tesseract.exe

abbyylang = string

Language to assume for abbyy OCR. Important for improving the OCR accuracy. This can also be set through the contents of a file in the currently processed directory. See the rclocrabbyy.py script. Typical values: English, French... See the ABBYY documentation.

abbyycmd = fn

Path for the abbyy command The ABBY directory is usually not in the path, so you should set this.

mhmboxquirks = string

Enable thunderbird/mozilla-seamonkey mbox format quirks Set this for the directory where the email mbox files are stored.

## SEE ALSO
recollindex(1) recoll(1)


reportbug.conf

package: reportbug-debian

title: reportbug.conf(5)

text:
# reportbug.conf(5)

## NAME
reportbug.conf - The configuration file for reportbug

## SYNOPSIS
/etc/reportbug.conf - The configuration file for reportbug, a program designed to report bugs in the Debian distribution

## DESCRIPTION
This manual page describes the layout of the reportbug and querybts configuration file and the available configuration options. The default location of the file is /etc/reportbug.conf and the options may be overriding in $HOME/.reportbugrc (which follows the same format as reportbug.conf).

Please note that any configuration file has to be a valid UTF-8 document, and not in a different locale; this is particularly important in situations where localized characters have to be used (like for realname).

## FILE FORMAT
Configuration options can be specified in the form

option-name option-value

True/False (boolean) options can be specified as

boolean-option

(if it's present, it's a True).

Usually, no-option will disable option if option is boolean.

Options can be specified in any order.

## OPTIONS
The summary of possible options (in alphabetical order) is as follows:

bts

The bug tracking system to use, see reportbug --bts=help for a list of currently supported BTSes.

cc (boolean)

Whether the reporter should be Cc:ed on the bug report.

check-available (boolean)

Whether packages.debian.org should be queried for newer releases of the package. In advanced and expert mode, incoming.debian.org and http://ftp-master.debian.org/new.html are also checked.

compress (boolean)

Whether modified configuration files included in the bug report should be stripped down.

config-files (boolean)

Whether modified configuration files should be included with the bug report.

editor

The editor to use to edit the bug report. Example: editor "emacs -nw"

email

Default From address of the bug email (override with environment variables, see reportbug(1)). Example: email "humberto@example.com"

envelopefrom

Specify the Envelope From mail header (also known as Return-path); by default it's the From address but it can be selected a different one in case the MTA doesn't canonicalize local users to public addresses.

list-cc-me (boolean)

Send a carbon copy of the report to your automatically detected email address after a report number is assigned, like the --list-cc-me option.

mbox_reader_cmd

Specify a command to open the bug reports mbox file. You can use %s to substitute the mbox file to be used, and %% to insert a literal percent sign. If no %s is specified, the mbox file name is supplied at the end of the argument list. Example: mbox_reader_cmd "mutt -f %s"

header

Additional headers to add to the bug email. Like: header "X-Debbugs-CC: debian-qa@lists.debian.org"

header "X-Silly-Header: I haven't edited my /etc/reportbug.conf"

header "X-Debbugs-No-Ack: please" # to suppress acknowledgments

Note that setting additional headers may not work reliably if the bug email is passed to an external MUA for submission.

http_proxy

Default HTTP proxy used to query the BTS (override with environment variables, see reportbug(1)). Example: http_proxy http://proxy.example.com:3128/

justification

The justification in case of a Release Critical bug (severity either 'critical', 'serious' or 'grave'). Example: justification "text here"

keyid

The GPG key to use, if different from the default one on the system. Example: keyid 12345678

maintonly

See the --maintonly entry in reportbug(1).

max_attachment_size

The max size any attachment can have. Example: max_attachment_size 5000000

mh

Use the mh mailer.

mirror

The address of a BTS mirror. Example: mirror http://mirror.address/

mode [novice|standard|advanced|expert]

The default operating mode for reportbug(1).

mta

The path to the MTA used. Any SMTP server on Debian should be OK with the default: mta /usr/sbin/sendmail

mua

The mail user agent to use (the default is empty, to use an internal mailer). Example: mua 'mutt -H'

mutt

Use the mutt mailer.

nmh

Use the nmh mailer.

no-check-uid (boolean)

Disables checking whether the UIDs are outside admin range (root is still checked).

no-debconf (boolean)

Disables adding the debconf-show output to the bug report.

no-query-source (boolean)

Disables querying the source packages for bugs.

offline

Disables all external queries.

outfile

Output the full email contents (including headers) to the specified file instead of sending it. Example: outfile "~/reportbug_report"

paranoid

Paranoid mode: print the whole email envelope before sending it.

printonly

Print the report on screen, don't sent it.

query-bts (boolean)

Whether the BTS should be queried for existing bug reports.

quiet

See the --report-quiet entry in reportbug(1).

realname

The default real-name in the From address of the bug email (override with environment variables, see reportbug(1)). Example: realname "Humberto Flores III"

replyto

The default Reply-To in the bug email (override with environment variables, see reportbug(1). Example: replyto "Humberto Flores <humflores@example.org>"

severity [critical|grave|serious|important|normal|minor|wishlist]

The default severity level of the bug reported. Setting this in the configuration file will disable prompting while running reportbug.

sign [gpg|pgp|gnupg|none]

Program used to digitally sign bug reports automatically ('none' to disable it).

smtphost

Use an MTA different from /usr/sbin/sendmail. A port number other than 25 can also be specified. Example: smtphost mail.example.com:2525

Use "smtphost localhost" to enable the internal MTA.

smtppasswd

The password to use for SMTP. Example: smtppasswd f10r35

smtpuser

The username to use for SMTP. Example: smtpuser hflores

smtptls

Enables TLS encryption for the SMTP connection, using STARTTLS. This setting is ignored if you connect to port 465, in which case SSL/TLS will always be used.

submit

Use submit as the bug submission address.

template

Use the template mode, bypasses all prompts and the output it sent to stdout.

ui [text|urwid|gtk]

The user interface that querybts(1) and reportbug(1) should use.

verify

Enables automatic verification of package installation before reporting using debsums, if available.

## SEE ALSO
reportbug(1), querybts(1)

## AUTHOR
reportbug was written by Chris Lawrence <lawrencc@debian.org> and it's now maintained by Sandro Tosi <morph@debian.org>.

This manual page was written by Y Giridhar Appaji Nag <giridhar@appaji.net> for the Debian project, but may be used by others.


rofi-script

package: rofi

title: rofi-script(5)

summary: Rofi format for scriptable modi.

text:
# rofi-script(5)

## NAME
rofi script mode - Rofi format for scriptable modi.

## DESCRIPTION
rofi supports modes that use simple scripts in the background to generate a list and process the result from user actions. This provide a simple interface to make simple extensions to rofi.

## USAGE
To specify a script mode, set a mode with the following syntax: "{name}:{executable}"

For example:

```
rofi -show fb -modi "fb:file_browser.sh"
```

The name should be unique.

## API
Rofi calls the executable without arguments on startup. This should generate a list of options, separated by a newline (\n) (This can be changed by the script). If the user selects an option, rofi calls the executable with the text of that option as the first argument. If the script returns no entries, rofi quits.

A simple script would be:

```
#!/usr/bin/env bash
if [ x"$@" = x"quit" ]
then

    exit 0
fi
echo "reload"
echo "quit"
```

This shows two entries, reload and quit. When the quit entry is selected, rofi closes.

## Environment
Rofi sets the following environment variable when executing the script:

### ROFI_RETV
An integer number with the current state:

- 0: Initial call of script.

- 1: Selected an entry.

- 2: Selected a custom entry.

- 10-28: Custom keybinding 1-19

### ROFI_INFO
Environment get set when selected entry get set with the property value of the 'info' row option, if set.

## Passing mode options
Extra options, like setting the prompt, can be set by the script. Extra options are lines that start with a NULL character (\0) followed by a key, separator (\x1f) and value.

For example to set the prompt:

```
    echo -en "\0prompt\x1fChange prompt\n"
```

The following extra options exists:

- prompt: Update the prompt text.

- message: Update the message text.

- markup-rows: If 'true' renders markup in the row.

- urgent: Mark rows as urgent. (for syntax see the urgent option in dmenu mode)

- active: Mark rows as active. (for syntax see the active option in dmenu mode)

- delim: Set the delimiter for for next rows. Default is '\n' and this option should finish with this. Only call this on first call of script, it is remembered for consecutive calls.

- no-custom: Only accept listed entries, ignore custom input.

## Parsing row options
Extra options for individual rows can be set. The extra option can be specified following the same syntax as mode option, but following the entry.

For example:

```
    echo -en "aap\0icon\x1ffolder\n"
```

The following options are supported:

- icon: Set the icon for that row.

- meta: Specify invisible search terms.

- nonselectable: If true the row cannot activated.

- info: Info that, on selection, gets placed in the ROFI_INFO environment variable. This entry does not get searched.

multiple entries can be passed using the \x1f separator.

```
    echo -en "aap\0icon\x1ffolder\x1finfo\x1ftest\n"
```

## DASH shell
If you use the dash shell for your script, take special care with how dash handles escaped values for the separators. See issue #1201 on github.

## SEE ALSO
rofi(1), rofi-sensible-terminal(1), dmenu(1), rofi-theme(5), rofi-theme-selector(1)

## AUTHOR
Qball Cow ⟨qball@gmpclient.org⟩

Rasmus Steinke ⟨rasi@xssn.at⟩

Quentin Glidic ⟨sardemff7+rofi@sardemff7.net⟩

Original code based on work by: Sean Pringle ⟨sean.pringle@gmail.com⟩

For a full list of authors, check the AUTHORS file.


rofi-theme

title: rofi-theme(5)

summary: Rofi theme format files

text:
# rofi-theme(5)

## NAME
rofi-theme - Rofi theme format files

## DESCRIPTION
The need for a new theme format was motivated by the fact that the way rofi handled widgets has changed. From a very static drawing of lines and text to a nice structured form of packing widgets. This change made it possible to provide a more flexible theme framework. The old theme format and config file are not flexible enough to expose these options in a user-friendly way. Therefore, a new file format has been created, replacing the old one.

## Encoding
The encoding of the file is utf-8. Both unix (\n) and windows (\r\n) newlines format are supported. But unix is preferred.

## Comments
C and C++ file comments are supported.

- Anything after // and before a newline is considered a comment.

- Everything between /* and */ is a comment.

Comments can be nested and the C comments can be inline.

The following is valid:

```
// Magic comment.
property: /* comment */ value;
```

However, this is not:

```
prop/*comment*/erty: value;
```

## White space
White space and newlines, like comments, are ignored by the parser.

This:

```
property: name;
```

Is identical to:

```
     property             :
name
;
```

## File extension
The preferred file extension for the new theme format is rasi. This is an abbreviation for rofi advanced style information.

## Basic Structure
Each element has a section with defined properties. Global properties can be defined in section * { }. Sub-section names begin with a hash symbol #.

It is advised to define the global properties section on top of the file to make inheritance of properties clearer.

```
/* Global properties section */
* {

    // list of properties
}
/* Element theme section. */
{element path} {

    // list of properties
}
{elements... } {

    // list of properties
}
```

If there are multiple sections with the same name, they are merged. Duplicate properties are overwritten and the last parsed entry kept.

## Global properties section
A theme can have one or more global properties sections. If there is more than one, they will be merged.

The global properties section denotes the defaults for each element. Each property of this section can be referenced with @{identifier} (See Properties section)

A global properties section is indicated with a * as element path.

## Element theme section
A theme can have multiple element theme sections.

The element path can consist of multiple names separated by whitespace or dots. Each element may contain any number of letters, numbers and -'s. The first element in the element path should always start with a #. Multiple elements can be specified by a ,.

This is a valid element name:

```
element normal.normal {

    background-color: blue;
}
button {

    background-color: blue;
}
```

And is identical to:

```
element normal normal, button {

    background-color: blue;
}
```

Each section inherits the global properties. Properties can be explicitly inherited from their parent with the inherit keyword. In the following example:

```
window {

 a: 1;

 b: 2;

 children: [ mainbox ];
}
mainbox {

    a: inherit;

    b: 4;

    c: 8;
}
```

The element mainbox will have the following set of properties (if mainbox is a child of window):

```
a: 1;
b: 4;
c: 8;
```

If multiple sections are defined with the same name, they are merged by the parser. If multiple properties with the same name are defined in one section, the last encountered property is used.

## Properties Format
The properties in a section consist of:

```
{identifier}: {value};
```

Both fields are mandatory for a property.

The identifier names the specified property. Identifiers can consist of any combination of numbers, letters and '-'. It must not contain any whitespace. The structure of the value defines the type of the property. The current parser does not define or enforce a certain type of a particular identifier. When used, values with the wrong type that cannot be converted are ignored.

The current theme format supports different types:

- a string

- an integer number

- a fractional number

- a boolean value

- a color

- text style

- line style

- a distance

- a padding

- a border

- a position

- a reference

- an orientation

- a list of keywords

- an environment variable

- Inherit

Some of these types are a combination of other types.

## String.IP • 2
Format: "[:print:]+"

A string is always surrounded by double quotes ("). Between the quotes there can be any printable character.

For example:

```
font: "Awasome 12";
```

The string must be valid UTF-8.

## Integer.IP • 2
Format: [-+]?[:digit:]+

An integer may contain any number.

For examples:

```
lines: 12;
```

## Real.IP • 2
Format: [-+]?[:digit:]+(\.[:digit:]+)?

A real is an integer with an optional fraction.

For example:

```
real: 3.4;
```

The following is not valid: .3, 3. or scientific notation: 3.4e-3.

## Boolean.IP • 2
Format: (true|false)

Boolean value is either true or false. This is case-sensitive.

For example:

```
dynamic: false;
```

## Color
rofi supports the color formats as specified in the CSS standard (1,2,3 and some of CSS 4)

- Format: #{HEX}{3} (rgb)

- Format: #{HEX}{4} (rgba)

- Format: #{HEX}{6} (rrggbb)

- Format: #{HEX}{8} (rrggbbaa)

- Format: rgb[a]({INTEGER},{INTEGER},{INTEGER}[, {PERCENTAGE}])

- Format: rgb[a]({INTEGER}%,{INTEGER}%,{INTEGER}%[, {PERCENTAGE}])

- Format: hsl[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PERCENTAGE}])

- Format: hwb[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PERCENTAGE}])

- Format: cmyk( {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE} [, {PERCENTAGE} ])

- Format: {named-color} [ / {PERCENTAGE} ]

The white-space format proposed in CSS4 is also supported.

The different values are:

- {HEX} is a hexadecimal number ('0-9a-f' case insensitive).

- {INTEGER} value can be between 0 and 255 or 0-100 when representing percentage.

- {ANGLE} is the angle on the color wheel, can be in deg, rad, grad or turn. When no unit is specified, degrees is assumed.

- {PERCENTAGE} can be between 0-1.0, or 0%-100%

-

{named-color} is one of the following colors:

AliceBlue, AntiqueWhite, Aqua, Aquamarine, Azure, Beige, Bisque, Black, BlanchedAlmond, Blue, BlueViolet, Brown, BurlyWood, CadetBlue, Chartreuse, Chocolate, Coral, CornflowerBlue, Cornsilk, Crimson, Cyan, DarkBlue, DarkCyan, DarkGoldenRod, DarkGray, DarkGrey, DarkGreen, DarkKhaki, DarkMagenta, DarkOliveGreen, DarkOrange, DarkOrchid, DarkRed, DarkSalmon, DarkSeaGreen, DarkSlateBlue, DarkSlateGray, DarkSlateGrey, DarkTurquoise, DarkViolet, DeepPink, DeepSkyBlue, DimGray, DimGrey, DodgerBlue, FireBrick, FloralWhite, ForestGreen, Fuchsia, Gainsboro, GhostWhite, Gold, GoldenRod, Gray, Grey, Green, GreenYellow, HoneyDew, HotPink, IndianRed, Indigo, Ivory, Khaki, Lavender, LavenderBlush, LawnGreen, LemonChiffon, LightBlue, LightCoral, LightCyan, LightGoldenRodYellow, LightGray, LightGrey, LightGreen, LightPink, LightSalmon, LightSeaGreen, LightSkyBlue, LightSlateGray, LightSlateGrey, LightSteelBlue, LightYellow, Lime, LimeGreen, Linen, Magenta, Maroon, MediumAquaMarine, MediumBlue, MediumOrchid, MediumPurple, MediumSeaGreen, MediumSlateBlue, MediumSpringGreen, MediumTurquoise, MediumVioletRed, MidnightBlue, MintCream, MistyRose, Moccasin, NavajoWhite, Navy, OldLace, Olive, OliveDrab, Orange, OrangeRed, Orchid, PaleGoldenRod, PaleGreen, PaleTurquoise, PaleVioletRed, PapayaWhip, PeachPuff, Peru, Pink, Plum, PowderBlue, Purple, RebeccaPurple, Red, RosyBrown, RoyalBlue, SaddleBrown, Salmon, SandyBrown, SeaGreen, SeaShell, Sienna, Silver, SkyBlue, SlateBlue, SlateGray, SlateGrey, Snow, SpringGreen, SteelBlue, Tan, Teal, Thistle, Tomato, Turquoise, Violet, Wheat, White, WhiteSmoke, Yellow, YellowGreen,transparent

For example:

```
background-color: #FF0000;
border-color: rgba(0,0,1, 0.5);
text-color: SeaGreen;
```

or

```
background-color: transparent;
text-color: Black;
```

## Text style.IP • 2
Format: (bold|italic|underline|strikethrough|none)

Text style indicates how the highlighted text is emphasized. None indicates that no emphasis should be applied.

- bold: make the text thicker then the surrounding text.

- italic: put the highlighted text in script type (slanted).

- underline: put a line under the highlighted text.

- strikethrough: put a line through the highlighted text.

- small caps: emphasise the text using capitalization.

For some reason small caps does not work on some systems.

## Line style.IP • 2
Format: (dash|solid)

Indicates how a line should be drawn. It currently supports:

* dash: a dashed line, where the gap is the same width as the dash

* solid: a solid line

## Distance.IP • 2
Format: {Integer}px

- Format: {Real}em

- Format: {Real}ch

- Format: {Real}%

- Format: {Integer}mm

A distance can be specified in 3 different units:

- px: Screen pixels.

- em: Relative to text height.

- ch: Relative to width of a single number.

- mm: Actual size in millimeters (based on dpi).

- %: Percentage of the monitor size.

Distances used in the horizontal direction use the monitor width. Distances in the vertical direction use the monitor height. For example:

```
   padding: 10%;
```

On a full-HD (1920x1080) monitor, it defines a padding of 192 pixels on the left and right side and 108 pixels on the top and bottom.

### Calculating sizes
Rofi supports some maths in calculating sizes. For this it uses the CSS syntax:

```
width: calc( 100% - 37px );
```

It supports the following operations:

- + : Add

- - : Subtract

- / : Divide

- * : Multiply

- % : Multiply

- min : Minimum of l or rvalue;

- max : Maximum of l or rvalue;

It uses the C precedence ordering.

## Padding.IP • 2
Format: {Integer}

- Format: {Distance}

- Format: {Distance} {Distance}

- Format: {Distance} {Distance} {Distance}

- Format: {Distance} {Distance} {Distance} {Distance}

If no unit is specified, pixels are assumed.

The different number of fields in the formats are parsed like:

- 1 field: all

- 2 fields: topbottom leftright

- 3 fields: top, leftright, bottom

- 4 fields: top, right, bottom, left

## Border.IP • 2
Format: {Integer}

- Format: {Distance}

- Format: {Distance} {Distance}

- Format: {Distance} {Distance} {Distance}

- Format: {Distance} {Distance} {Distance} {Distance}

- Format: {Distance} {Line style}

- Format: {Distance} {Line style} {Distance} {Line style}

- Format: {Distance} {Line style} {Distance} {Line style} {Distance} {Line style}

- Format: {Distance} {Line style} {Distance} {Line style} {Distance} {Line style} {Distance} {Line style}

Borders are identical to padding, except that each distance field has a line style property.

When no unit is specified, pixels are assumed.

## Position
Indicate a place on the window/monitor.

•

Format: (center|east|north|west|south|north east|north west|south west|south east)

```
north west   |    north    |  north east
-------------|-------------|------------

      west   |   center    |  east
-------------|-------------|------------
south west   |    south    |  south east
```

## Visibility
It is possible to hide widgets:

inputbar {

enabled: false; }

## Reference.IP • 2
Format: @{PROPERTY NAME}

A reference can point to another reference. Currently, the maximum number of redirects is 20. A property always refers to another property. It cannot be used for a subpart of the property. For example, this is not valid:

```
highlight: bold @pink;
```

But this is:

```
* {

    myhigh: bold #FAA;
}
window {

    highlight: @myhigh;
}
```

## Orientation.IP • 2
Format: (horizontal|vertical)

Specify the orientation of the widget.

## List of keywords.IP • 2
Format: [ keyword, keyword ]

A list starts with a '[' and ends with a ']'. The entries in the list are comma-separated. The keyword in the list refers to an widget name.

## Environment variable.IP • 2
Format: ${:alnum:}

This will parse the environment variable as the property value. (that then can be any of the above types). The environment variable should be an alphanumeric string without white-space.

```
* {

    background-color: ${BG};
}
```

## Inherit.IP • 2
Format: inherit

Inherits the property from its parent widget.

```
mainbox {

    border-color: inherit;
}
```

## ELEMENTS PATHS
Element paths exists of two parts, the first part refers to the actual widget by name. Some widgets have an extra state.

For example:

```
element selected {
}
```

Here element selected is the name of the widget, selected is the state of the widget.

The difference between dots and spaces is purely cosmetic. These are all the same:

```
element .selected {
element.selected {
}
element selected {
}
```

## Name
The current widgets available in rofi:

- window

- overlay: the overlay widget.

- mainbox: The mainbox box.

- inputbar: The input bar box.

- box: the horizontal @box packing the widgets

- case-indicator: the case/sort indicator @textbox

- prompt: the prompt @textbox

- entry: the main entry @textbox

- num-rows: Shows the total number of rows.

- num-filtered-rows: Shows the total number of rows after filtering.

- listview: The listview.

- scrollbar: the listview scrollbar

- element: a box in the listview holding the entries

- element-icon: the widget in the listview's entry showing the (optional) icon

- element-index: the widget in the listview's entry keybindable index (1,2,3..0)

- element-text: the widget in the listview's entry showing the text.

- mode-switcher: the main horizontal @box packing the buttons.

- button: the buttons @textbox for each mode

- message: The container holding the textbox.

- textbox: the message textbox

Note that these path names match the default theme. Themes that provide a custom layout will have different elements, and structure.

## State
State: State of widget

Optional flag(s) indicating state of the widget, used for theming.

These are appended after the name or class of the widget.

### Example:
button selected.normal { }

element selected.urgent { }

Currently only the entrybox and scrollbar have states:

### Entrybox:
{visible modifier}.{state}

Where visible modifier can be:

* normal: no modification

* selected: the entry is selected/highlighted by user

* alternate: the entry is at an alternating row (uneven row)

Where state is:

* normal: no modification

* urgent: this entry is marked urgent

* active: this entry is marked active

These can be mixed.

Example:

```
nametotextbox selected.active {

    background-color: #003642;

    text-color: #008ed4;
}
```

Sets all selected textboxes marked active to the given text and background color. Note that a state modifies the original element, it therefore contains all the properties of that element.

### Scrollbar
The scrollbar uses the handle state when drawing the small scrollbar handle. This allows the colors used for drawing the handle to be set independently.

## SUPPORTED PROPERTIES
The following properties are currently supported:

### all widgets:.IP • 2
enabled: enable/disable the widget

- padding: padding Padding on the inside of the widget

- margin: padding Margin on the outside of the widget

- border: border Border around the widget (between padding and margin)/

- border-radius: padding Sets a radius on the corners of the borders.

- background-color: color Background color

- border-color: color Color of the border

### window:.IP • 2
font: string The font used in the window

•

transparency: string Indicating if transparency should be used and what type: real - True transparency. Only works with a compositor. background - Take a screenshot of the background image and use that. screenshot - Take a screenshot of the screen and use that. Path to png file - Use an image.

•

location: position The place of the anchor on the monitor

•

anchor: anchor The anchor position on the window

•

fullscreen: boolean Window is fullscreen.

•

width: distance The width of the window

•

x-offset: distance

•

y-offset: distance The offset of the window to the anchor point, allowing you to push the window left/right/up/down

### scrollbar:.IP • 2
background-color: color

- handle-width: distance

- handle-color: color

- border-color: color

### box:.IP • 2
orientation: orientation

Set the direction the elements are packed.

•

spacing: distance

Distance between the packed elements.

### textbox:.IP • 2
background-color: color

- border-color: the color used for the border around the widget.

- font: the font used by this textbox (string).

- str: the string to display by this textbox (string).

- vertical-align: vertical alignment of the text (0 top, 1 bottom).

- horizontal-align: horizontal alignment of the text (0 left, 1 right).

- text-color: the text color to use.

- highlight: text style {color}. color is optional, multiple highlight styles can be added like: bold underline italic #000000;

- width: override the desired width for the textbox.

- content: Set the displayed text (String).

- placeholder: Set the displayed text (String) when nothing is entered.

- placeholder-color: Color of the placeholder text.

- blink: Enable/Disable blinking on an input textbox (Boolean).

### listview:.IP • 2
columns: integer Number of columns to show (at least 1)

- fixed-height: boolean Always show lines rows, even if fewer elements are available.

- dynamic: boolean True if the size should change when filtering the list, False if it should keep the original height.

- scrollbar: boolean If the scrollbar should be enabled/disabled.

- scrollbar-width: distance Width of the scrollbar

- cycle: boolean When navigating, it should wrap around

- spacing: distance Spacing between the elements (both vertical and horizontal)

- lines: integer Number of rows to show in the list view.

- layout: orientation Indicate how elements are stacked. Horizontal implements the dmenu style.

- reverse: boolean Reverse the ordering (top down to bottom up).

- fixed-columns: boolean Do not reduce the number of columns shown when number of visible elements is not enough to fill them all.

Each element is a box called element. Each element can contain an element-icon and element-text.

### listview text highlight:
The element-text widget in the listview is the one used to show the text. On this widget set the highlight property (only place this property is used) to change the style of highlighting. The highlight property consist of the text-style property and a color.

To disable highlighting:

```
  element-text {

    highlight: None;

  }
```

To set to red underlined:

```
  element-text {

    highlight: underline red;

  }
```

## Layout
The new format allows the layout of the rofi window to be tweaked extensively. For each widget, the themer can specify padding, margin, border, font, and more. It even allows, as an advanced feature, to pack widgets in a custom structure.

### Basic structure
The whole view is made out of boxes that pack other boxes or widgets. The box can be vertical or horizontal. This is loosely inspired by GTK ⟨http://gtk.org/⟩.

The current layout of rofi is structured as follows:

```
|------------------------------------------------------------------------------------|
| window {BOX:vertical}                                                              |
| |-------------------------------------------------------------------------------|  |
| | mainbox  {BOX:vertical}                                                       |  |
| | |---------------------------------------------------------------------------| |  |
| | | inputbar {BOX:horizontal}                                                 | |  |
| | | |---------| |-----------------------------------------------------| |---| | |  |
| | | | prompt  | | entry                                               | |ci | | |  |
| | | |---------| |-----------------------------------------------------| |---| | |  |
| | |---------------------------------------------------------------------------| |  |
| |                                                                               |  |
| | |---------------------------------------------------------------------------| |  |
| | | message                                                                   | |  |
| | | |-----------------------------------------------------------------------| | |  |
| | | | textbox                                                               | | |  |
| | | |-----------------------------------------------------------------------| | |  |
| | |---------------------------------------------------------------------------| |  |
| |                                                                               |  |
| | |-----------------------------------------------------------------------------|  |
| | | listview                                                                    |  |
| | |-----------------------------------------------------------------------------|  |
| |                                                                               |  |
| | |---------------------------------------------------------------------------| |  |
| | |  mode-switcher {BOX:horizontal}                                           | |  |
| | | |---------------|   |---------------|  |--------------| |---------------| | |  |
| | | | Button        |   | Button        |  | Button       | | Button        | | |  |
| | | |---------------|   |---------------|  |--------------| |---------------| | |  |
| | |---------------------------------------------------------------------------| |  |
| |-------------------------------------------------------------------------------|  |
|------------------------------------------------------------------------------------|
```

ci is the case-indicator

### Error message structure

```
|-----------------------------------------------------------------------------------|
| window {BOX:vertical}                                                             |
| |------------------------------------------------------------------------------|  |
| | error-message {BOX:vertical}                                                 |  |
| | |-------------------------------------------------------------------------|  |  |
| | | textbox                                                                 |  |  |
| | |-------------------------------------------------------------------------|  |  |
| |------------------------------------------------------------------------------|  |
|-----------------------------------------------------------------------------------|
```

### Advanced layout
The layout of rofi can be tweaked by packing the 'fixed' widgets in a custom structure.

The following widgets are fixed, as they provide core rofi functionality:

- prompt

- entry

- overlay

- case-indicator

- message

- listview

- mode-switcher

- num-rows

- num-filtered-rows

The following keywords are defined and can be used to automatically pack a subset of the widgets. These are used in the default theme as depicted in the figure above.

- mainbox Packs: inputbar, message, listview, mode-switcher

- inputbar Packs: prompt,entry,case-indicator

Any widget name starting with textbox is a textbox widget, others are box widgets and can pack other widgets.

There are several special widgets that can be used by prefixing the name of the widget:

- textbox: This is a textbox widget. The displayed string can be set with str.

- icon: This is an icon widget. The displayed icon can be set with filename and size with size.

- button: This is a textbox widget that can have a 'clickable' action. The action can be set to: ok accept entry. custom accept custom input. ok|alternate: accept entry and launch alternate action (for run launch in terminal). custom|alternate: accept custom input and launch alternate action.

To specify children, set the children property (this always happens on the box child, see example below):

```
children: [prompt,entry,overlay,case-indicator];
```

The theme needs to be updated to match the hierarchy specified.

Below is an example of a theme emulating dmenu:

```
* {

    background-color:      Black;

    text-color:            White;

    border-color:          White;

    font:            "Times New Roman 12";
}
window {

    anchor:     north;

    location:   north;

    width:      100%;

    padding:    4px;

    children:   [ horibox ];
}
horibox {

    orientation: horizontal;

    children:   [ prompt, entry, listview ];
}
listview {

    layout:     horizontal;

    spacing:    5px;

    lines:      10;
}
entry {

    expand:     false;

    width:      10em;
}
element {

    padding: 0px 2px;
}
element selected {

    background-color: SteelBlue;
}
```

### Padding and margin
Just like CSS, rofi uses the box model for each widget.

```
|-------------------------------------------------------------------|
| margin                                                            |
|  |-------------------------------------------------------------|  |
|  | border                                                      |  |
|  | |---------------------------------------------------------| |  |
|  | | padding                                                 | |  |
|  | | |-----------------------------------------------------| | |  |
|  | | | content                                             | | |  |
|  | | |-----------------------------------------------------| | |  |
|  | |---------------------------------------------------------| |  |
|  |-------------------------------------------------------------|  |
|-------------------------------------------------------------------|
```

Explanation of the different parts:

- Content - The content of the widget.

- Padding - Clears an area around the widget. The padding shows the background color of the widget.

- Border - A border that goes around the padding and content. The border use the border-color of the widget.

- Margin - Clears an area outside the border. The margin is transparent.

The box model allows us to add a border around elements, and to define space between elements.

The size of each margin, border, and padding can be set. For the border, a linestyle and radius can be set.

### Spacing
Widgets that can pack more then one child widget (currently box and listview) have the spacing property. This property sets the distance between the packed widgets (both horizontally and vertically).

```
|---------------------------------------|
|  |--------| s |--------| s |-------|  |
|  | child  | p | child  | p | child |  |
|  |        | a |        | a |       |  |
|  |        | c |        | c |       |  |
|  |        | i |        | i |       |  |
|  |        | n |        | n |       |  |
|  |--------| g |--------| g |-------|  |
|---------------------------------------|
```

### Advanced box packing
More dynamic spacing can be achieved by adding dummy widgets, for example to make one widget centered:

```
|--------------------------------------------|
|  |-----------|  |--------|  |-----------|  |
|  | dummy     |  | child  |  | dummy     |  |
|  | expand: y |  |        |  | expand: y |  |
|  |           |  |        |  |           |  |
|  |           |  |        |  |           |  |
|  |           |  |        |  |           |  |
|  |-----------|  |--------|  |-----------|  |
|--------------------------------------------|
```

If both dummy widgets are set to expand, child will be centered. Depending on the expand flag of child the remaining space will be equally divided between both dummy and child widget (expand enabled), or both dummy widgets (expand disabled).

## DEBUGGING
To get debug information from the parser, run rofi like:

```
G_MESSAGES_DEBUG=Parser rofi -show run
```

Syntax errors are shown in a popup and printed out to command line with the above command.

To see the elements queried during running, run:

```
G_MESSAGES_DEBUG=Theme rofi -show run
```

To test minor changes, part of the theme can be passed on the command line, for example to set it to full-screen:

```
rofi -theme-str '#window { fullscreen:true;}' -show run
```

To print the current theme, run:

```
rofi -dump-theme
```

## Media support
Parts of the theme can be conditionally loaded, like the CSS @media option.

```
@media ( min-width: 120 ) {
}
```

It supports the following keys as constraint:

- min-width: load when width is bigger or equal then value.

- max-width: load when width is smaller then value.

- min-height: load when height is bigger or equal then value.

- max-height: load when height is smaller then value.

- min-aspect-ratio load when aspect ratio is over value.

- max-aspect-ratio: load when aspect ratio is under value.

- monitor-id: The monitor id, see rofi -help for id's.

@media takes an integer number or a fraction, for integer number px can be added.

```
@media ( min-width: 120 px ) {
}
```

## Multiple file handling
The rasi file format offers two methods of including other files. This can be used to modify existing themes, or have multiple variations on a theme.

- import: Import and parse a second file.

- theme: Discard theme, and load file as a fresh theme.

Syntax:

```
@import "myfile"
@theme "mytheme"
```

The specified file can either by name, filename,full path.

If a filename is provided, it will try to resolve it in the following order:

- ${XDG_CONFIG_HOME}/rofi/themes/

- ${XDG_CONFIG_HOME}/rofi/

- ${XDG_DATA_HOME}/rofi/themes/

- ${INSTALL PREFIX}/share/rofi/themes/

A name is resolved as a filename by appending the .rasi extension.

## EXAMPLES
Several examples are installed together with rofi. These can be found in {datadir}/rofi/themes/, where {datadir} is the install path of rofi data. When installed using a package manager, this is usually: /usr/share/.

## SEE ALSO
rofi(1), rofi-script(5), rofi-theme-selector(1)


pppoe.conf

package: rp-pppoe-client

title: pppoe.conf(5)

text:
# pppoe.conf(5)

## NAME
pppoe.conf - Configuration file used by pppoe-start(8), pppoe-stop(8), pppoe-status(8) and pppoe-connect(8).

## DESCRIPTION
/etc/ppp/pppoe.conf is a shell script which contains configuration information for RP-PPPoE scripts. Note that pppoe.conf is used only by the various pppoe-* shell scripts, not by pppoe itself.

pppoe.conf consists of a sequence of shell variable assignments. The variables and their meanings are:

ETH

The Ethernet interface connected to the DSL modem (for example, eth0).

USER

The PPPoE user-id (for example, b1xxnxnx@sympatico.ca).

SERVICENAME

If this is not blank, then it is passed with the -S option to pppoe. It specifies a service name to ask for. Usually, you should leave it blank.

ACNAME

If this is not blank, then it is passed with the -C option to pppoe. It specifies the name of the access concentrator to connect to. Usually, you should leave it blank.

DEMAND

If set to a number, the link is activated on demand and brought down after after DEMAND seconds. If set to no, the link is kept up all the time rather than being activated on demand.

DNSTYPE

One of NOCHANGE, SPECIFY or SERVER. If set to NOCHANGE, pppoe-connect will not adjust the DNS setup in any way. If set to SPECIFY, it will use resolvconf for adding values of DNS1 and DNS2 to /etc/resolv.conf. If set to SERVER, it will supply the usepeerdns option to pppd.

DNS1, DNS2

IP addresses of DNS servers if you use DNSTYPE=SPECIFY.

NONROOT

If the line NONROOT=OK (exactly like that; no whitespace or comments) appears in the configuration file, then pppoe-wrapper will allow non-root users to bring the conneciton up or down. The wrapper is installed only if you installed the rp-pppoe-gui package.

USEPEERDNS

If set to "yes", then pppoe-connect will supply the usepeerdns option to pppd, which causes it to obtain DNS server addresses from the peer and create a new /etc/resolv.conf file. Otherwise, pppoe-connect will not supply this option, and pppd will not modify /etc/resolv.conf.

CONNECT_POLL

How often (in seconds) pppoe-start should check to see if a new PPP interface has come up. If this is set to 0, the pppoe-start simply initiates the PPP session, but does not wait to see if it comes up successfully.

CONNECT_TIMEOUT

How long (in seconds) pppoe-start should wait for a new PPP interface to come up before concluding that pppoe-connect has failed and killing the session.

PING

A character which is echoed every CONNECT_POLL seconds while pppoe-start is waiting for the PPP interface to come up.

FORCEPING

A character which is echoed every CONNECT_POLL seconds while pppoe-start is waiting for the PPP interface to come up. Similar to PING, but the character is echoed even if pppoe-start's standard output is not a tty.

PIDFILE

A file in which to write the process-ID of the pppoe-connect process (for example, /var/run/pppoe.pid). Two additional files ($PIDFILE.pppd and $PIDFILE.pppoe) hold the process-ID's of the pppd and pppoe processes, respectively.

SYNCHRONOUS

An indication of whether or not to use synchronous PPP (yes or no). Synchronous PPP is safe on Linux machines with the n_hdlc line discipline. (If you have a file called "n_hdlc.o" in your modules directory, you have the line discipline.) It is not recommended on other machines or on Linux machines without the n_hdlc line discipline due to some known and unsolveable race conditions in a user-mode client.

CLAMPMSS

The value at which to "clamp" the advertised MSS for TCP sessions. The default of 1412 should be fine.

LCP_INTERVAL

How often (in seconds) pppd sends out LCP echo-request packets.

LCP_FAILURE

How many unanswered LCP echo-requests must occur before pppd concludes the link is dead.

PPPOE_TIMEOUT

If this many seconds elapse without any activity seen by pppoe, then pppoe exits.

FIREWALL

One of NONE, STANDALONE or MASQUERADE. If NONE, then pppoe-connect does not add any firewall rules. If STANDALONE, then it clears existing firewall rules and sets up basic rules for a standalone machine. If MASQUERADE, then it clears existing firewall rules and sets up basic rules for an Internet gateway. If you run services on your machine, these simple firewall scripts are inadequate; you'll have to make your own firewall rules and set FIREWALL to NONE.

PPPOE_EXTRA

Any extra arguments to pass to pppoe

PPPD_EXTRA

Any extra arguments to pass to pppd

LINUX_PLUGIN

If non-blank, the full path of the Linux kernel-mode PPPoE plugin (typically /etc/ppp/plugins/rp-pppoe.so.) This forces pppoe-connect to use kernel-mode PPPoE on Linux 2.4.x systems. This code is experimental and unsupported. Use of the plugin causes pppoe-connect to ignore CLAMPMSS, PPPOE_EXTRA, SYNCHRONOUS and PPPOE_TIMEOUT.

RESOLVCONF_NAME

Name for resolvconf entry. When used DNSTYPE=SPECIFY this name passed to resolvconf with -a option.

By using different configuration files with different PIDFILE settings, you can manage multiple PPPoE connections. Just specify the configuration file as an argument to pppoe-start and pppoe-stop.

## SEE ALSO
pppoe(8), pppoe-connect(8), pppoe-start(8), pppoe-stop(8), pppd(8), pppoe-setup(8), pppoe-wrapper(8)


rssh.conf

package: rssh

title: rssh.conf(5)

summary: configuration file for rssh

text:
# rssh.conf(5)

## NAME
/etc/rssh.conf - configuration file for rssh

## OVERVIEW
rssh.conf is the configuration file for rssh. It allows the system administrator to control the behavior of the shell. Configuration keywords are either used by themselves on a line, or followed by an equal sign ('=') and a configuration value. Comments start with a hash ('#') and can occur anywhere on the line. Configuration options are case insensitive. Spaces at the beginning or end of line, or between the equal sign and the configuration keywords or values are ignored. If the value of a configuration option contains spaces, it (or at least the space) must be enclosed in either single or double quotes.

A default configuration file is provided with the source distribution of rssh. If the configuration file is missing or contains errors, ssh will lock out all users. If a config file is present, the default is to lock out users if no services have been explicitly allowed.

New in v2.1 is the ability to configure options on a per-user basis, using the user keyword. More details are below.

## CONFIGURATION KEYWORDS
allowscp

Tells the shell that scp is allowed.

allowsftp

Tells the shell that sftp is allowed.

allowcvs

Tells the shell that cvs is allowed.

allowrdist

Tells the shell that rdist is allowed.

allowrsync

Tells the shell that rsync is allowed.

umask

Sets the umask value for file creations in the scp/sftp session. This is normally set at login time by the user's shell. In order not to use the system default, rssh must set the umask.

logfacility

Allows the system administrator to control what syslog facility rssh logs to. The facilities are the same as those used by syslogd.conf(5), or the C macros for the facilities can be used instead. For example: logfacility=user

logfacility=LOG_USER

are equivalent, and tell rssh to use the user facility for logging to syslog.

chrootpath

Causes rssh (actually a helper program) to call the chroot() system call, changing the root of the file system to whatever directory is specified. Note that the value on the right hand side of the equal sign is the name of a directory, not a command. For example: chrootpath=/usr/chroot

will change the root of the virtual file system to /usr/chroot, preventing the user from being able to access anything below /usr/chroot in the file system, and making /usr/chroot appear to be the root directory. Care must be taken to set up a proper chroot jail; see the file CHROOT in the rssh source distribution for hints about how to do this. See also the chroot(2) man page.

If the user's home directory (as specified in /etc/passwd) is underneath the path specified by this keyword, then the user will be chdir'd into their home directory. If it is not, then they will be chdir'd to the root of the chroot jail.

In other words, if the jail is /chroot, and your user's home directory is /chroot/home/user, then once rssh_chroot_helper changes the root of the system, it will cd into /home/user inside the jail. However, if your user's home directory is given as /home/user in /etc/passwd, then even if that directory exists in the jail, the chroot helper will not try to cd there. The user's normal home directory must live inside the jail for this to work.

user

The user keyword allows for the configuration of options on a per-user basis. THIS KEYWORD OVERRIDES ALL OTHER KEYWORDS FOR THE SPECIFIED USER. That is, if you use a user keyword for user foo, then foo will use only the settings in that user line, and not any of the settings set with the keywords above. The user keyword's argument consists of a group of fields separated by a colon (':'), as shown below. The fields are, in order: username

The username of the user for whom the entry provides options

umask The umask for this user, in octal, just as it would be specified to the shell

access bits Five binary digits, which indicate whether the user is allowed to use rsync, rdist, cvs, sftp, and scp, in that order. One means the command is allowed, zero means it is not.

path The directory to which this user should be chrooted (this is not a command, it is a directory name). See chroot_path above for complete details.

For example, you might have something like this:

user = luser:022:00001:

This does the following: for the user with the username "luser", set the umask to 022, disallow sftp, and allow scp. Because there is no chroot path specified, the user will not be chrooted, regardless of default options set with the keywords above. If you wanted this user to be chrooted, you would need to specify the chroot path explicitly, even if it should be the same as that set using the chrootpath keyword. Remember that if there are spaces in the path, you need to quote it, something like this:

user = "luser:022:00001:/usr/local/chroot dir"

See the default rssh.conf file for more examples.

## SEE ALSO
rssh(1), sshd(8), ssh(1), scp(1), sftp(1), syslogd.conf(5), chroot(2).