[gentoo-commits] proj/R_overlay:master commit in: man/

[André Erdmann]

commit:     ef6225dc3fec998e73ec0db342bbf4b8481d84da
Author:     André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Tue Jul 10 17:01:44 2012 +0000
Commit:     André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Tue Jul 10 17:01:44 2012 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=ef6225dc

man pages

---
 man/roverlay-deprules.5 |  173 +++++++++++++++++++++++++++++++++++++++++++++++
 man/roverlay-repo.5     |  139 +++++++++++++++++++++++++++++++++++++
 man/roverlay.1          |    7 +-
 3 files changed, 315 insertions(+), 4 deletions(-)

diff --git a/man/roverlay-deprules.5 b/man/roverlay-deprules.5
new file mode 100644
index 0000000..2e1ce98
--- /dev/null
+++ b/man/roverlay-deprules.5
@@ -0,0 +1,173 @@
+.\" groff -Tascii -man
+.TH "ROVERLAY-DEPRULES" "5" "July 10 2012" "Linux/Gentoo?" "R Overlay"
+.SH "NAME"
+deprules \- R overlay dependency rule configuration
+.SH "SYNOPSIS"
+\fBsimple-deprules.conf\fR
+.SH "DESCRIPTION"
+A simple dependency rule file defines one or more rules
+that are used for dependency resolution in \fBroverlay(1)\fR.
+.PP
+A rule defines which \fIdep_string\fR read from an R package resolves
+to a specific \fIdependency\fR.
+\fIdependency\fR can be a \fBDEPEND atom\fR or \fBDynamic DEPEND\fR,
+see \fBebuild(5)\fR.
+\'The R programming language\',
+for example, should resolve to \'dev\-lang/R\'.
+Other dependencies such as packages from @system,
+should be ignored since they\'re always provided.
+This is also possible.
+
+.IP "\(bu simple rules"
+These rules are very simple and match a \fIdep_string\fR exactly.
+.IP "\(bu fuzzy rules"
+These rules try to find a match for \fIdep_string\fR using string interpolation, metrics and/or regex matches.
+.SS "RULE VARIANTS"
+.IP "\(bu normal"
+\fIdep_string\fR will be resolved as \fIdependency\fR.
+.IP "\(bu ignore"
+\fIdep_string\fR will be ignored if it matches an ignore rule.
+
+.SS "RULE STUBS"
+There\'s a special (shorter) syntax for dependencies
+that are resolved within the created overlay.
+For example, if your \fIOVERLAY_CATEGORY\fR is \'sci\-R\',
+\'zoo\' should be resolved as \'sci\-R/zoo\'.
+This rule can be written as a single word, \'zoo\'.
+The advantage is that you don\'t have to write the
+overlay category into the rule file.
+These stubs are called \fBselfdeps\fR.
+
+
+.SS "BASIC SYNTAX"
+.IP "\(bu rule that matches one \fIdep_string\fR"
+[\fIkeyword\fR and/or \fIdependency\fR] :: \fIdep_string\fR
+.br
+.IP "\(bu rule that matches multiple \fIdep_string\fRs"
+This replaces " :: \fIdep_string\fR" by a multiline variant
+.br
+[\fIkeyword\fR and/or \fIdependency\fR] \&{
+.br
+\& \fIdep_string\fR
+.br
+\& [\fIdep_string\fR]
+.br
+\& [\fIdep_string\fR]
+.br
+\& \&.\&.\&.
+.br
+\&}
+.br
+.IP "\fBselfdep\fR rule"
+[\fIkeyword\fR]\fIshort_dependency\fR
+.br
+where \fIshort_dependency\fR is a package name (\fBDEPEND atom\fR without version, category).
+This is the only way to specify selfdeps.
+
+.SS "ADDITIONAL SYNTAX"
+Comments start with \'#\'.
+.PP
+There are two special keywords that both cause reading a rule file to stop, \'#! BREAKPARSE\' and \'#! NOPARSE\'.
+The line must exactly be one of these keywords (no additional content at the end of the line).
+
+
+
+.SH "SIMPLE RULES"
+A simple rule resolves exact string matches (case-insensitive).
+.SS "SYNTAX"
+.IP "\(bu normal"
+\fIdependency\fR :: \fIdep_string\fR
+.IP "\(bu ignore"
+! :: \fIdep_string\fR
+.IP "\(bu selfdep, normal"
+\fIshort_dependency\fR
+.IP "\(bu selfdep, ignored"
+!\fIshort_dependency\fR
+
+.SH "FUZZY RULES"
+A fuzzy rule tries to resolve, i.e. "resolve \fIdep_string\fR as \fIdependency\fR if it \fIsomehow\fR matches a \fIfuzzy_string\fR".
+The \fIsomehow\fR is up to the implementation, it currently includes:
+.SS "EXACT MATCH"
+This is equal to the \fBSIMPLE RULES\fR
+.SS "VERSION\-RELATIVE MATCH"
+Uses regexes to identify \fIdep_string\fRs
+that only differ in the requested version (and/or version syntax).
+"R (\&>\&= 2.15)" and "R[2.10]", for instance, should be resolved as "dev\-lang/R".
+A single fuzzy\-rule "~dev\-lang/R :: R" does this and resolves them as
+"\&>=dev\-lang/R\-2.15" and "\&>=dev\-lang/R\-2.10", respectively.
+Note that this is just an example, \fBroverlay(1)\fR will filter out dependencies on
+dev\-lang/R when the version is \&<= the lowest version available in portage.
+.br
+In detail, this method matches if
+.br
+\& \fIdep_string\fR ~= \fIfuzzy_string\fR \&<\fIversion_statement\fR\&>,
+.br
+where \fIversion_statment\fR is something like \&>=2.10, \&!=0.9, 1.0, \&<5,
+optionally enclosed with braces ((), [], {}).
+Whitespace is ignored unless \fIversion_statment\fR is not enclosed,
+in which case some whitespace (more than zero chars) must exist between
+\fIfuzzy_string\fR and \fIversion_statment\fR.
+
+.SS SYNTAX
+Fuzzy rules use ~ and % as keyword.
+.IP "\(bu normal"
+\&~\fIdependency\fR :: \fIfuzzy_string\fR
+.IP "\(bu ignore"
+\&%\fIdependency\fR :: \fIfuzzy_string\fR
+.IP "\(bu selfdep"
+\&~\fIshort_dependency\fR
+.IP "\(bu selfdep, ignored"
+\&%\fIshort_dependency\fR
+
+.SH "EXAMPLES"
+Example 1:
+.RS 1
+A rule that matches many dependencies on dev\-lang/R,
+for example "r 2.12", "R(\&>= 2.14)", "R [\&<2.10]", "r{  !2.12 }", and "R".
+.RS 2
+
+\&~dev\-lang/R :: R
+.RE
+.RE
+.PP
+Example 2:
+.RS 1
+A rule that fuzzy-matches a zoo package selfdep.
+.RS 2
+
+\&~zoo
+.RE
+.RE
+.PP
+Example 3:
+.RS 1
+A standard self dep, resolves "tuneR", "tuner", ... as "sci\-R/tuneR"
+(\fIOVERLAY_CATEGORY\fR/tuneR).
+.RS 2
+
+\&tuneR
+.RE
+.RE
+.PP
+Example 4:
+.RS 1
+A simple multiline rule that ignores some text.
+This is a good way to deal with free-style text found in
+some R package DESCRIPTION files.
+.RS 2
+
+! :: {
+.RS 2
+see README
+.br
+read INSTALL
+.br
+[which can be downloaded from http://...]
+.br
+.RE
+}
+.RE
+.RE
+
+.SH "SEE ALSO"
+.BR "roverlay(1)"

diff --git a/man/roverlay-repo.5 b/man/roverlay-repo.5
new file mode 100644
index 0000000..c8e1270
--- /dev/null
+++ b/man/roverlay-repo.5
@@ -0,0 +1,139 @@
+.\" groff -Tascii -man
+.TH "ROVERLAY-REPO" "5" "July 10 2012" "Linux/Gentoo?" "R Overlay"
+.SH "NAME"
+roverlay-repo \- R overlay repo config file
+.SH "SYNOPSIS"
+.BR "repo.list"
+.SH "DESCRIPTION"
+A repo config file is used to define repositories, both local and remote, and
+uses ConfigParser syntax (known from .ini files).
+.SS "REPO ENTRIES"
+A repo entry describes where to find R packages that will be used for overlay creation,
+and optionally where and how to get the R packages (using \fBREPO TYPES\fR).
+It also defines how ebuilds can download the R packages (used as \fISRC_URI\fR variable in ebuilds).
+.SS "REPO TYPES"
+There are two types of repos, "rsync" and "local" ones:
+.IP "\(bu local repositories"
+A \fBlocal repo\fR represents a directory with R packages in it.
+It will never be modified (i.e. synced) and has no special options.
+.IP "\(bu rsync repositories"
+An \fBrsync repo\fR uses a local directory to sync with a remote.
+Its directory will be modified whenever syncing (using the rsync program).
+It behaves like a local repo if syncing is disabled.
+.br
+These rsync options are always passed to rsync:
+.br
+\fB
+\-\-links, \-\-safe-links, \-\-times, \-\-compress,
+\-\-dirs, \-\-prune-empty-dirs, \-\-force, \-\-delete,
+\-\-human-readable, \-\-stats, \-\-chmod=ugo=r,u+w,Dugo+
+\fR
+.PP
+.SH "VARIABLES"
+Each repository is introduced with [\fIsection_name\fR] and has to declare some options.
+.SS "common options"
+.TP
+.BR "src_uri" " = \fIuri\fR"
+This is used to determine the \fISRC_URI\fR variable used in ebuilds.
+\fIuri\fR usually starts with 'http://' which can be left out,
+"localhost/R-packages" is the same uri as "http://localhost/R-packages".
+Always required.
+.TP
+.BR "name" " = \fIrepo_name\fR"
+Specify a name for the repository.
+Optional, defaults to \fIsection_name\fR
+which should be fine in most cases. The repo name should not contain whitespace.
+.TP
+.BR "type" " = \fItype\fR"
+Set the repo type. Optional, defaults to rsync (see \fBREPO_TYPES\fR).
+.TP
+.BR "directory" " = \fIdirectory\fR"
+Set the local package directory.
+Optional, defaults to \fIDISTFILES_ROOT\fR/\fIname\fR
+(see \fIDISTFILES_ROOT\fR in \fBR\-overlay.conf\fR).
+
+.SS "special options for local repos"
+None.
+
+.SS "special options for rsync repos"
+.TP
+.BR "rsync_uri" " = \fIrsync_uri\fR"
+Set the uri used for downloading the R packages into \fIdirectory\fR.
+Always required.
+.TP
+.BR "recursive" " = yes"
+If set to 'yes': pass '\-\-recursive' to rsync.
+This is optional and not enabled by default 'cause downloading sub directories is not always desirable.
+In case of CRAN, this would download the whole R package archive and all R releases.
+.TP
+.BR "extra_rsync_opts" " = \fIopts\fR"
+A whitespace-separated list of extra options that will be passed to rsync.
+Useful to in-/exclude files/dirs, show progress while running rsync etc.
+Options must not contain whitespace/quote chars.
+Note that the options won't be verified - this is \fBtotally unsafe!\fR
+.SH "EXAMPLES"
+Example 1:
+.RS 1
+A local directory with packages in /var/www/R-packages
+that are available on your network via "http://package_host/R-packages".
+.RS 2
+
+[local_packages]
+.br
+type      = local
+.br
+src_uri   = http://package_host/R-packages
+.br
+directory = /var/www/R-packages
+.RE
+.RE
+.PP
+Example 2:
+.RS 1
+A local directory with packages manually downloaded from CRAN.
+The directory will be automatically set to \fIDISTFILES_ROOT\fR/CRAN/selected.
+.RS 2
+
+[CRAN/selected]
+.br
+type    = local
+.br
+src_uri = http://cran.r-project.org/src/contrib
+.RE
+.RE
+.PP
+Example 3:
+.RS 1
+An rsync repo for CRAN's current packages (CRAN without archive).
+The local DISTFILES_ROOT dir will be set to \fIDISTFILES_ROOT\fR/CRAN/all.
+This needs about 2.5G disk space (as of July 2012).
+.RS 2
+
+[CRAN/all]
+.br
+src_uri   = http://cran.r-project.org/src/contrib
+.br
+rsync_uri = cran.r-project.org::CRAN/src/contrib
+.RE
+.RE
+.PP
+Example 4:
+.RS 1
+A repo that selectively syncs packages from CRAN that start with 'r' or 'R'
+to \fIDISTFILES_ROOT\fR/CRAN/only_letter_R. This can be realized using \fIextra_rsync_opts\fR.
+Also showing progress during transfer.
+This needs about 300M disk space.
+.RS 2
+
+[CRAN/only_letter_R]
+.br
+src_uri          = http://cran.r-project.org/src/contrib
+.br
+rsync_uri        = cran.r-project.org::CRAN/src/contrib
+.br
+extra_rsync_opts = \-\-include=r* \-\-include=R* \-\-exclude=* \-\-progress
+.RE
+.RE
+
+.SH "SEE ALSO"
+.BR "roverlay(1)"

diff --git a/man/roverlay.1 b/man/roverlay.1
index ba8e24a..02c78ed 100644
--- a/man/roverlay.1
+++ b/man/roverlay.1
@@ -104,9 +104,8 @@ Run overlay creation with sync, all options (overlay name/dir,...) are read from
 roverlay \-\-from \fIpkgdir\fR \-O \fIoverlay\fR \-N R_Overlay \-\-field-definition \fIfield_definition\fR \-D \fIdeprules\fR
 Run overlay creation for packages from \fIpkgdir\fR and write the overlay named R_Overlay to \fIoverlay\fR.
 Use the given \fIfield_definition\fR and \fIdeprules\fR files.
+.br
 !!! This should do without a config file (FIXME)
 .SH "SEE ALSO"
-.BR "R-overlay.conf(5)",
-.BR "roverlay-field_definition(5)",
-.BR "roverlay-repo(5)"
-
+.BR "roverlay\-repo(5)",
+.BR "roverlay\-deprules(5)"