From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) by finch.gentoo.org (Postfix) with ESMTP id 565711381F4 for ; Mon, 13 Aug 2012 16:34:28 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id DF3CDE07D5; Mon, 13 Aug 2012 16:34:16 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) by pigeon.gentoo.org (Postfix) with ESMTP id 68111E07D5 for ; Mon, 13 Aug 2012 16:34:16 +0000 (UTC) Received: from hornbill.gentoo.org (hornbill.gentoo.org [94.100.119.163]) (using TLSv1 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 88B0B1B402B for ; Mon, 13 Aug 2012 16:34:15 +0000 (UTC) Received: from localhost.localdomain (localhost [127.0.0.1]) by hornbill.gentoo.org (Postfix) with ESMTP id 55147E5441 for ; Mon, 13 Aug 2012 16:34:14 +0000 (UTC) From: "André Erdmann" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "André Erdmann" Message-ID: <1344875641.7254100883c2c25da9e154990a9e3864c8712332.dywi@gentoo> Subject: [gentoo-commits] proj/R_overlay:master commit in: doc/rst/, doc/html/ X-VCS-Repository: proj/R_overlay X-VCS-Files: doc/html/usage.html doc/rst/usage.rst X-VCS-Directories: doc/rst/ doc/html/ X-VCS-Committer: dywi X-VCS-Committer-Name: André Erdmann X-VCS-Revision: 7254100883c2c25da9e154990a9e3864c8712332 X-VCS-Branch: master Date: Mon, 13 Aug 2012 16:34:14 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: 0e7d8089-2a83-476b-9d72-237290beddc3 X-Archives-Hash: 27be13ff428e020928eced475b1089a5 commit: 7254100883c2c25da9e154990a9e3864c8712332 Author: André Erdmann mailerd de> AuthorDate: Mon Aug 13 16:34:01 2012 +0000 Commit: André Erdmann mailerd de> CommitDate: Mon Aug 13 16:34:01 2012 +0000 URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=72541008 usage doc: depres console and config options --- doc/html/usage.html | 625 +++++++++++++++++++++++++++++++++++++++++++++------ doc/rst/usage.rst | 499 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 1044 insertions(+), 80 deletions(-) diff --git a/doc/html/usage.html b/doc/html/usage.html index 37e3c27..bc9cb85 100644 --- a/doc/html/usage.html +++ b/doc/html/usage.html @@ -320,67 +320,79 @@ ul.auto-toc {

Contents

-

1   Introduction

+

1   Introduction

roverlay is Automatically Generated Overlay of R packages;; GSoC Project;; <>;;

-

2   Installation

+

2   Installation

-

2.1   Prerequisites

+

2.1   Prerequisites

  • python >= 2.7 (tested with python 2.7 and 3.2)

    • @@ -425,13 +437,13 @@ writing to a tmpfs, most time is spent for Manifest creation>

-

2.2   via emerge (Gentoo)

+

2.2   via emerge (Gentoo)

A live ebuild is available, roverlay-9999.ebuild. Add it to your local overlay and run emerge roverlay, which will also install all config files into /etc/roverlay.

-

2.3   Manual Installation

+

2.3   Manual Installation

After installing the dependencies as listed in Prerequisites, clone the roverlay git repo and then install roverlay and its python modules:

@@ -465,7 +477,7 @@ any config files!

-

2.4   Using roverlay without installation

+

2.4   Using roverlay without installation

This is possible, too. Make sure to meet the dependencies as listed in Prerequisites. Then, simply clone the git repository to a local directory that @@ -485,9 +497,9 @@ will later be referenced as the R Overlay src directory.

-

3   Running Roverlay

+

3   Running Roverlay

-

3.1   Required configuration steps

+

3.1   Required configuration steps

roverlay needs a configuration file to run.

If you've installed roverlay with emerge, it will look for the config file in that order:

@@ -532,7 +544,13 @@ see Providing a

This sets the global log level, which is used for all log formats that don't override this option. Valid log levels are DEBUG, INFO, WARN/WARNING, ERROR and CRITICAL.

-

Example: LOG_LEVEL = WARNING

+

Example: LOG_LEVEL = WARNING

+
+

Caution!

+

Be careful with low log levels, especially DEBUG. +They produce a lot of messages that you probably don't want to see +and increase the size of log files dramatically.

+
LOG_LEVEL_CONSOLE

This sets the console log level.

@@ -549,8 +567,8 @@ have reasonable defaults if roverlay has been installed using emerg
SIMPLE_RULES_FILE
-

This option lists the dependency rules files that should be used -for dependency resolution (see +

This option lists dependency rule files and/or directories with +such files that should be used for dependency resolution (see Dependency Rules / Resolving Dependencies). Although not required, this option is recommended since ebuild creation without dependency rules fails for most R packages.

@@ -581,10 +599,13 @@ named R-packages.eclass should be part of your installation.

+

There's another option that is useful if you want to create new dependency +rules, LOG_FILE_UNRESOLVABLE, which will write all unresolvable dependencies +to the specified file (one dependency string per line).

For details and a full configuration reference, see Configuration Reference.

-

3.2   Running it

+

3.2   Running it

If you've installed roverlay, you can run it with roverlay, otherwise you'll have to cd into the R overlay src directory and run ./roverlay.py.

In any case, the basic roverlay script usage is

@@ -690,12 +711,13 @@ is specified.

Starts an interactive dependency resolution console that supports rule creation/deletion, loading rules from files, writing rules to files and resolving dependencies.

-

Meant for testing only.

+

Meant for testing only.

+

More information can be found in the DepRes Console section.

-

3.3   Providing a package mirror

+

3.3   Providing a package mirror

<No recommendations at this time. The current ManifestCreation implementation creates a directory <distfiles root>/__tmp__ with symlinks to all packages, which could be used for providing packages, but this may change @@ -704,7 +726,7 @@ in near future since external Manifest creation is too slow

-

4   Implementation Overview

+

4   Implementation Overview

This section gives a basic overview of how roverlay works.

<how roverlay basically works:>

    @@ -757,13 +779,13 @@ and may decide to write p's ebuild now (or later)
-

4.1   Repositories / Getting Packages

+

4.1   Repositories / Getting Packages

roverlay is capable of downloading R packages via rsync and http, and is able to use any packages locally available. The concrete method used to get and use the packages is determined by the concrete type of a repository and that's what this section is about.

-

4.1.1   A word about repo config files

+

4.1.1   A word about repo config files

Repo config files use ConfigParser syntax (known from ini files).

Each repo entry section is introduced with [<repo name>] and defines

    @@ -774,7 +796,7 @@ and where they should be stored verification

Such options are declared with <option> = <value> in the repo entry.

-

The common options for repository entries are:

+

The common options for repository entries are:

  • type, which declares the repository type. Available types are:

    @@ -801,7 +823,7 @@ creating the default directory.

-

4.1.2   Rsync repos

+

4.1.2   Rsync repos

Runs rsync to download packages. Automatic sync retries are supported if rsync's exit codes indicates chances of success. For example, up to 3 retries are granted if rsync returns @@ -844,7 +866,7 @@ Options with whitespace are not supported.

-

4.1.3   Getting packages from a repository that supports http only

+

4.1.3   Getting packages from a repository that supports http only

This is your best bet if the remote is a repository but doesn't offer rsync access. Basic digest verification is supported (MD5). The remote has to have a package list file, typically named @@ -894,7 +916,7 @@ Defaults to src_uri/pkglist_file

-

4.1.4   Getting packages from several remotes using http and a package list

+

4.1.4   Getting packages from several remotes using http and a package list

This is not a real repository type, instead it creates a local repository by downloading single R packages from different remotes. Its only requirement is that a package is downloadable via http. @@ -921,7 +943,7 @@ file would be:

-

4.1.5   Using local directories

+

4.1.5   Using local directories

Using local package directories is possible, too.

Example:

@@ -944,9 +966,9 @@ you should consider using one of the websync repo types,
-

4.2   Dependency Rules / Resolving Dependencies

+

4.2   Dependency Rules / Resolving Dependencies

-

4.2.1   Dependency types

+

4.2.1   Dependency types

Every dependency string has a dependency type that declares how a dependency should be resolved. It has one or more of these properties:

@@ -974,7 +996,7 @@ gets the "package dependency and optional" type, whereas the SystemRequirements gets "system dependency and mandatory".

-

4.2.2   Simple Dependency Rules

+

4.2.2   Simple Dependency Rules

Simple dependency rules use a dictionary and string transformations to resolve dependencies. Fuzzy simple dependency rules extend these by a set of regexes, which allows to resolve many dependency strings that @@ -983,7 +1005,7 @@ minimally differ (e.g. only in the required version and/or comments: dictionary entry.

This is the only rule implementation currently available.

-

4.2.2.1   Rule Variants

+

4.2.2.1   Rule Variants

default
The expected behavior of a dictionary-based rule: It matches one or more @@ -994,7 +1016,7 @@ resolve them as nothing.
-

4.2.2.2   Rule types

+

4.2.2.2   Rule types

Simple Rules

A simple rule resolves exact string matches (case-insensitive).

@@ -1035,7 +1057,7 @@ as "<dev-lang/R-2.14"
-

4.2.2.3   Rule File Examples

+

4.2.2.3   Rule File Examples

This sections lists some rule file examples. See Rule File Syntax for a formal<precise,..?> description.

@@ -1087,7 +1109,7 @@ if you've installed roverlay with emerge, else in <R Overlay src directory>/simple-deprules.d.

-

4.2.2.4   Rule File Syntax

+

4.2.2.4   Rule File Syntax

Simple dependency rule files have a special syntax. Each rule is introduced with the resolving dependency prefixed by a keychar that sets the rule type if required. The dependency strings resolved by this rule are listed @@ -1190,7 +1212,7 @@ will be read as normal dependency strings.

-

4.3   Expected Overlay Result / Structure of the generated overlay

+

4.3   Expected Overlay Result / Structure of the generated overlay

Assuming that you're using the default configuration (where possible) and the R-packages eclass file, the result should look like:

@@ -1210,26 +1232,485 @@ the R-packages eclass file, the result should look like:
+
+

5   DepRes Console

+

As previously stated, the DepRes Console is only meant for testing. +It's an interactive console with the following features:

+
    +
  • resolve dependencies
    • +
  • create new dependency rules (only single line rules)
    • +
  • create dependency rules for each R package found in a directory
    • +
  • load rules from files
    • +
  • save rules to a file
    • +
+

Rules are managed in a set. These so-called rule pools are organized in +a first-in-first-out data structure that allows +to create or remove them easily at runtime.

+

Running roverlay depres_console will print a welcome message that +lists all available commands and a few usage hints.

+

For reference, these commands are currently available:

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
commanddescription
help, +hlists all commands
help --list, +h --listlists all help topics for which help is available
help <cmd>, +h <cmd>prints a command-specific help message
load <file|dir>, +l <file|dir>loads a rule file or a directory with rule files +into a new rule pool
load_conf, +lcloads the rule files listed in the config file +into a new rule pool
addrule <rule> ++ <rule>creates a new rule and adds it to the topmost, +i.e. latest rule pool. This command uses +Rule File Syntax, but multi line rules are +not supported.
add_pool, +<<creates a new rule pool
unwind, +>>removes the topmost rule pool and all of its +rules
resolve <dep>, +? <dep>tries to resolve the given dependency string and +prints the result
print, pprints the rules of the topmost rule pool
print all, p allprints the rules of all rule pools
write <file>, +w <file>writes the rules of the topmost rule pool into +<file>
cd <dir>changes the working directory, also creates it if +necessary
scandir <dir>, +sd <dir>creates dependency rules for each R package found +in <dir>
set, unsetprints the status of currently (in)active modes
set <mode>, +unset <mode>set or unsets <mode>. There's only one mode to +control, the shlex mode which controls how +command arguments are parsed
mkhelpverifies that each accessible command has a help +message
exit, qq, qexit the DepRes Console
+
+
Example Session:
+
+== depres console ==
+Run 'help' to list all known commands
+More specifically, 'help <cmd>' prints a help message for the given
+command, and 'help --list' lists all help topics available
+Use 'load_conf' or 'lc' to load the configured rule files
+
+commands: load, unwind, set, help, >>, load_conf, <<, cd, mkhelp,
+resolve, lc, add_pool, addrule, h, +, l, li, write, p, r, ?, w, print,
+sd, unset, scandir
+exit-commands: q, qq, exit
+
+cmd % + ~dev-lang/R :: R language
+new rules:
+~dev-lang/R :: R language
+--- ---
+command succeeded.
+
+cmd % ? R language
+Trying to resolve ('R language',).
+Resolved as: ('dev-lang/R',)
+
+cmd % ? R language [ 2.15 ]
+Trying to resolve ('R language [ 2.15 ]',).
+Resolved as: ('>=dev-lang/R-2.15',)
+
+cmd % ? R
+Trying to resolve ('R',).
+Channel returned None. At least one dep couldn't be resolved.
+
+cmd % p
+~dev-lang/R :: R language
+
+cmd % >>
+Pool removed from resolver.
+
+cmd % p
+
+cmd % ? R language
+Trying to resolve ('R language',).
+Channel returned None. At least one dep couldn't be resolved.
+
+cmd % exit
+
+
+
+
-

5   Configuration Reference

+

6   Configuration Reference

-

5.1   Dependency Rules

+

6.1   Dependency Rules

<merge with basic..overview::deprules>

-

5.2   Repositories

+

6.2   Repositories

<merge with basic..overview::repo>

-

5.3   Main Config

+

6.3   Main Config

+

The main config file uses "<option> = <value>" syntax, comment lines start +with #. Variable substitution ("${X}") is not supported. Quotes around +the value are optional and allow to span long values over multiple lines. +Whitespace is ignored, file paths must not contain whitespace.

+

Some options have value type restrictions. These value types are used:

+
+
log_level
+
Value has to be a log level. Available choise are DEBUG, INFO, WARN, +WARNING, ERROR and CRITICAL.
+
bool
+

Value is a string that represents a boolean value.

+

This table illustrates which values strings are accepted:

+ ++++ + + + + + + + + + + + + + + + + +
string valueboolean value
y, yes, on, 1, true, enabledTrue
n, no, off, 0, false, disabledFalse
<any other value>not allowed
+
+
+

There are also some implicit value types:

+
+
list
+
This means that a option has several values that are separated by +whitespace. Quotation marks have to be used to specify more than one +value.
+
file, dir
+
A value that represents a file system location will be expanded ('~' will +be replaced by the user's home etc.). +Additionaly the value has to be a file (or directory) if it exists.
+
<empty>
+
Specifying empty values often leads to errors if an option has value type +restrictions. It's better to comment out options.
+
+

The following sections will list all config entries.

+
+

6.3.1   misc options

+
+
DISTFILES
+
Alias for DISTFILES_ROOT.
+
DISTFILES_ROOT
-
<>
+

The root directory of per-repository package directories. Repos will create +their package directories in this directory unless they specify another +location (see repo config options).

+

This option is required.

+
+
+
+
DISTROOT
+
Alias for DISTFILES_ROOT.
+
+
+
+

6.3.2   overlay options

+
+
ECLASS
+
Alias to OVERLAY_ECLASS.
+
+
+
OVERLAY_CATEGORY
+

Sets the category of created ebuilds. There are no value type restrictions +for this option, but values with a slash / lead to errors.

+

Defaults to sci-R.

+
+
+
+
OVERLAY_DIR
+

Sets the directory of the overlay that will be created.

+

This option is required.

+
+
+
+
OVERLAY_ECLASS
+

A list of eclass files that will be imported into the overlay and inherited +in all created ebuilds. +Note that overlay creation fails if any of the specified eclass files +cannot be imported. +Eclass files must end with '.eclass' or have no file extension.

+

Defaults to <not set>, which means that no eclass files will be used. +This is not useful, since created ebuilds rely on an eclass for phase +functions like src_install().

+
+
+
+
OVERLAY_KEEP_NTH_LATEST
+

Setting this option to a value > 0 enables keeping of max. value ebuilds +per R package. All others will be removed.

+

Defaults to <not set>, which disables this feature and keeps all ebuilds.

+
-

The main config file uses shell syntax.

+
+
OVERLAY_NAME
+

Sets the name of the created overlay that will be written into +OVERLAY_DIR/profiles/repo_name. This file will be rewritten on every +roverlay run that includes the create command.

+

Defaults to R_Overlay.

+
+
+
+
+

6.3.3   other config files

+

Some config config options are split from the main config file for various +reasons:

+ +

The paths to these files have to be listed in the main config file and +can be overridden with the appropriate command line options.

+
+
FIELD_DEFINITION
+

Path to the field definition file that controls how the DESCRIPTION file +of R packages is read.

+

This option is required.

+
+
+
+
FIELD_DEFINITION_FILE
+
Alias to FIELD_DEFINITION.
+
+
+
REPO_CONFIG
+

A list of one or more repo config files.

+

This option is required.

+
+
+
+
REPO_CONFIG_FILE
+
Alias to REPO_CONFIG.
+
+
+
REPO_CONFIG_FILES
+
Alias to REPO_CONFIG.
+
+
+
SIMPLE_RULES_FILE
+

A list of files and directories with dependency rules. +Directories will be non-recursively scanned for rule files.

+

This option is not required, but recommended since roverlay cannot do +much without dependency resolution.

+
+
+
+
SIMPLE_RULES_FILES
+
Alias to SIMPLE_RULES_FILE.
+
+
+
+

6.3.4   logging

+
+
LOG_DATE_FORMAT
+

The date format used in log messages.

+

Defaults to %F %H:%M:%S. +(<<explain the date format by referencing to date(1) +or python's logging->? module>>)

+
+
+
+
LOG_ENABLED
+

Globally enable or disable logging. The value has to be a bool. +Setting this option to True allows logging to occur, while False +disables logging entirely. +Log target such as console or file have to be enabled +to actually get any log messages.

+

Defaults to True.

+
+
+
+
LOG_LEVEL
+

Sets the default log level. Log targets that don't have their own log +level set will use this value.

+

Defaults to <not set> - all log targets will use their own defaults

+
+
+
+

6.3.4.1   console logging

+
+
LOG_CONSOLE
+

Enables/Disables logging to console. The value has to be a bool.

+

Defaults to True.

+
+
+
+
LOG_FORMAT_CONSOLE
+

Sets the format for console log messages.

+

Defaults to %(levelname)-8s %(name)-14s: %(message)s.

+
+
+
+
LOG_LEVEL_CONSOLE
+

Sets the log level for console logging.

+

Defaults to INFO.

+
+
+
+
+

6.3.4.2   file logging

+
+
LOG_FILE
+

Sets the log file. File logging will be disabled if this option does not +exist or is commented out even if LOG_FILE_ENABLED is set to True.

+

Defaults to <not set>.

+
+
+
+
LOG_FILE_BUFFERED
+

Enable/Disable buffering of log entries in memory before they're written +to the log file. Enabling this reduces I/O blocking, especially when using +low log levels. The value must be a bool.

+

Defaults to enabled.

+
+
+
+
LOG_FILE_BUFFER_COUNT
+

Sets the number of log entries to buffer at most. Can be decreased to +lower memory consumption when using log entry buffering.

+

Defaults to 250.

+
+
+
+
LOG_FILE_ENABLED
+

Enables/Disable file logging. The value has to be a bool.

+

Defaults to enabled, in which case file logging is enabled if LOG_FILE +is set, else disabled.

+
+
+
+
LOG_FILE_FORMAT
+

Sets the format used for log messages written to a file.

+

Defaults to %(asctime)s %(levelname)-8s %(name)-10s: %(message)s.

+
+
+
+
LOG_FILE_LEVEL
+

Sets the log level for file logging.

+

Defaults to WARNING.

+
+
+
+
LOG_FILE_ROTATE
+

A bool that enables/disables log file rotation. If enabled, the log file +will be rotated on every script run and max. LOG_FILE_ROTATE_COUNT log +files will be kept.

+

Defaults to disabled.

+
+
+
+
LOG_FILE_ROTATE_COUNT
+

Sets the number of log files to keep at most.

+

Defaults to 3 and has no effect if LOG_FILE_ROTATE is disabled.

+
+
+
+
+
+

6.3.5   options for debugging, manual dependency rule creation and testing

+
+
DESCRIPTION_DIR
+

A directory where all description data read from an R package will be +written into. This can be used to analyze/backtrack overlay creation +results.

+

Defaults to <not set>, which disables writing of description data files.

+
+
+
+
EBUILD_PROG
+

Name or path of the ebuild executables that is required for (external) +Manifest file creation. A wrong value will cause ebuild creation late, +which is a huge time loss, so make sure that this option is properly set.

+

Defaults to ebuild, which should be fine in most cases.

+
+
+
+
LOG_FILE_UNRESOLVABLE
+

A file where all unresolved dependency strings will be written into +on roverlay exit. Primarily useful for creating new rules.

+

Defaults to <not set>, which disables this feature.

+
+
+
+
RSYNC_BWLIMIT
+

Set a max. average bandwidth usage in kilobytes per second. +This will pass '--bwlimit=<value>' to all rsync commands.

+

Defaults to <not set>, which disables bandwidth limitation.

+
+
+
-
-

5.4   Field Definition

+
+

6.4   Field Definition

The field definition file uses ConfigParser syntax. For an example, see default field definition file.

Each information field has its own section which declares a set of options @@ -1310,9 +1791,9 @@ are ignored, too, the main difference is the log message.

-

6   Appendix

+

7   Appendix

-

6.1   Default Field Definition File

+

7.1   Default Field Definition File

This is the default field definition file (without any ignored fields):

 [Description]

diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index ebf8aa0..3099e83 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -200,6 +200,12 @@ The following options should be set before running *roverlay*:
 
       Example: LOG_LEVEL = WARNING
 
+      .. caution::
+
+         Be careful with low log levels, especially *DEBUG*.
+         They produce a lot of messages that you probably don't want to see
+         and increase the size of log files dramatically.
+
    LOG_LEVEL_CONSOLE
       This sets the console log level.
 
@@ -214,8 +220,8 @@ The following options should also be set (most of them are required), but
 have reasonable defaults if *roverlay* has been installed using *emerge*:
 
    SIMPLE_RULES_FILE
-      This option lists the dependency rules files that should be used
-      for dependency resolution (see
+      This option lists dependency rule files and/or directories with
+      such files that should be used for dependency resolution (see
       `Dependency Rules / Resolving Dependencies`_).
       Although not required, this option is **recommended** since ebuild
       creation without dependency rules fails for most R packages.
@@ -248,6 +254,9 @@ have reasonable defaults if *roverlay* has been installed using *emerge*:
 
       Example: OVERLAY_ECLASS = ~/roverlay/eclass/R-packages.eclass
 
+There's another option that is useful if you want to create new dependency
+rules, LOG_FILE_UNRESOLVABLE_, which will write all unresolvable dependencies
+to the specified file (one dependency string per line).
 
 For details and a full configuration reference, see `Configuration Reference`_.
 
@@ -350,11 +359,13 @@ sync
 	This will download all packages from the configured remotes.
 
 depres_console, depres
-	Starts an interactive dependency resolution console that supports rule
-	creation/deletion, loading rules from files, writing rules to files
-	and resolving dependencies.
+   Starts an interactive dependency resolution console that supports rule
+   creation/deletion, loading rules from files, writing rules to files
+   and resolving dependencies.
+
+   Meant for **testing only**.
 
-	Meant for **testing only**.
+   More information can be found in the `DepRes Console`_ section.
 
 ----------------------------
  Providing a package mirror
@@ -433,6 +444,8 @@ and is able to use any packages locally available. The concrete method used
 to get and use the packages is determined by the concrete
 **type of a repository** and that's what this section is about.
 
+.. _repo config:
+
 ++++++++++++++++++++++++++++++++
  A word about repo config files
 ++++++++++++++++++++++++++++++++
@@ -449,6 +462,8 @@ Each repo entry section is introduced with ``[]`` and defines
 
 Such options are declared with ``