diff options
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-10-24 09:49:29 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-10-24 09:49:29 +0000
commitbb972990af73df1029479745a51b264315cb5824 (patch)
parent2663953de292d3029d4c345fe938c1c24f442608 (diff)
Docs updates
5 files changed, 17 insertions, 168 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index a243842..7331c24 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -14,7 +14,6 @@ docfiles = \
doc_changelog.doxygen \
doc_portage_differences.doxygen \
doc_news.doxygen \
- doc_security_advisories.doxygen \
doc_configuration_files.doxygen \
doc_migration_howto.doxygen \
diff --git a/doc/doc_bootstrap_howto.doxygen b/doc/doc_bootstrap_howto.doxygen
index eba5821..7731685 100644
--- a/doc/doc_bootstrap_howto.doxygen
+++ b/doc/doc_bootstrap_howto.doxygen
@@ -32,13 +32,6 @@ There're ebuilds in the tree, or in <a
href="http://svn.pioto.org/viewvc/paludis/overlay/"> the Paludis overlay</a> if
you need SVN ebuilds.
-You'll need libebt, libwrapiter, eselect and Subversion. If you're using the QA
-tools (<code>--enable-qa</code>) you will also need pcre++ (and pcre, by
-extension) and libxml2. You'll also need either g++-3.4, g++-4.1 or some other
-reasonably standard C++ compiler along with a complete standard library
-implementation (so no uClibc++). If you're trying to run on non-Linux, you'll
-also need to fix a few includes and submit a patch.
Make sure the test suite passes (either <code>FEATURES="test"</code> for
Portage, or <code>make check</code>). If it fails, don't continue until you
figure out why.
@@ -270,8 +263,8 @@ almost certainly need --dl-drop-circular at this stage.
paludis --config-suffix bootstrap --install --pretend --dl-drop-all sys-apps/baselayout
sudo paludis --config-suffix bootstrap --install --dl-drop-all sys-apps/baselayout
-paludis --config-suffix bootstrap --install --pretend --dl-drop-circular system
-sudo paludis --config-suffix bootstrap --install --dl-drop-circular system
+paludis --config-suffix bootstrap --install --pretend --dl-circular discard system
+sudo paludis --config-suffix bootstrap --install --dl-circular discard system
Note that system will pull in Portage. That's a profiles thing that's
diff --git a/doc/doc_known_issues.doxygen b/doc/doc_known_issues.doxygen
index db7b562..6301cf8 100644
--- a/doc/doc_known_issues.doxygen
+++ b/doc/doc_known_issues.doxygen
@@ -20,7 +20,8 @@ This document also describes some things that are not bugs or missing functional
Problem: <code>sys-fs/udev</code> will fail at the merge stage.
Workaround: Use <code>~arch</code> for this package. We don't support merging
-fancy things like device files.
+fancy things like device files. Neither does Portage, but Portage isn't well
+behaved enough to error out on it either -- it just does something silly.
\subsection KnownIssuesKDE Some KDE libraries are broken on some amd64 profiles
@@ -75,6 +76,13 @@ Non-Problem: Paludis doesn't have an equivalent to --resume --skipfirst in Porta
Rationale: Too unreliable, too flaky and far too widely abused. There's talk of echoing a command (<code>paludis -i10 =sys-apps/foo-1.23-r1 =app-misc/fnord-2 ...</code>) that can be used to resume if an ebuild exits with an error, but that's not set in stone.
+\subsection KnownNonIssuesNice Automatic Niceness Support
+Non-Problem: There's no <code>PORTAGE_NICENESS</code> equivalent.
+Rationale: Learn how to use <code>nice</code>. There's no <code>GCC_NICENESS</code> or <code>VIM_NICENESS</code>
diff --git a/doc/doc_mainpage.doxygen b/doc/doc_mainpage.doxygen
index 2990dff..5a8c5e3 100644
--- a/doc/doc_mainpage.doxygen
+++ b/doc/doc_mainpage.doxygen
@@ -13,9 +13,12 @@ This is the documentation for Paludis, the other package manager. It is availabl
\section userdocs For End Users
Paludis is still undergoing heavy development. It is not a mature solution, and
-still has quite a few missing features. You <b>will</b> run into bugs if you use
-Paludis (some of which may leave your system unusable). Most ebuild authors do
-not test their code with both package managers.
+still has quite a few missing features. For the sake of covering our asses, we
+remind you that using Paludis might break your system (using Portage might break
+your system too, but they don't like to admit that up front). Paludis is much
+stricter than Portage when it comes to circular dependencies, ebuilds doing dodgy
+things, enforcing ROOT, merging non-directories over directories and the like, so
+expect to see error messages when using naughty ebuilds.
If you find this acceptable, read \link BootstrapHowto the Bootstrap HOWTO
\endlink for how to set up a chroot or make a stage, or \link MigrationHowto the
diff --git a/doc/doc_security_advisories.doxygen b/doc/doc_security_advisories.doxygen
deleted file mode 100644
index 1f290f8..0000000
--- a/doc/doc_security_advisories.doxygen
+++ /dev/null
@@ -1,154 +0,0 @@
-/* vim: set ft=cpp tw=80 sw=4 et spell spelllang=en : */
-\page SecurityAdvisoriesSpecs Handling of Security Advisories
-\version 1
-\author Danny van Dyk <kugelfang@gentoo.org>
-\author Stefan Cornelius <dercorny@gentoo.org>
-\section SecurityAdvisoriesSpecsAbstract Abstract
-This specification describes how security advisory files should be named,
-stored, structured and handled by Paludis.
-\section SecurityAdvisoriesSpecsNaming Naming
-The format of file names shall be
- advisory-YYYYMM-XX.conf
-where XX is a unique ID that is increased with every GLSA in the month and
-YYYYMM is the usual date notation.
-\section SecurityAdvisoriesSpecsStorage Storage
-Security advisories shall be stored as text files in
- ${repo}/metadata/security
-by default. Files within subdirectories shall not be parsed by Paludis. However,
-the user can change this path in the repository's configuration file. The key's
-name shall be <code>securitydir</code>.
-Once tree wide Manifest support (aka as Manifest2 support) will be implemented,
-all advisories should be listed by a Manifest file and checked against this
-manifest before parsing them.
-\section SecurityAdvisoriesSpecsStructure Structure
-The file format shall consist of a RFC 822 style header and a trailing text
-body. This document describes specification <code>0</code>. The following keys shall be
-understood by Paludis:
-The following keys are mandatory and must be unique in the advisory.
-Paludis shall throw an exception otherwise.
- <tr>
- <td>Id</td>
- <td>Unique identifier of this advisory. Must be in <code>YYYYMM-XX</code> format and
- reflect the suffix of the advisory's file name.</td>
- </tr>
- <tr>
- <td>Title</td>
- <td>A string that describes the kind of vulnerability indicated by the advisory.</td>
- </tr>
- <tr>
- <td>Access</td>
- <td>Describes if if the vulnerability can be exploited by <code>local</code> or
- <code>remote</code> users.</td>
- </tr>
- <tr>
- <td>Last-Modified</td>
- <td>A date string that describes when the advisory was changed.</td>
- </tr>
- <tr>
- <td>Revision</td>
- <td>The advisory's revision number. It must start with <code>1.0</code> and should be
- increased by <code>0.1</code> whenever the advisory's metadata was changed
- substantially.</td>
- <tr>
- <td>Severity</td>
- <td>The severity of the vulnerabilities described by the advisory.
- Supported values are <code>high</code>, <code>normal</code> and <code>low</code>.</td>
- </tr>
- <tr>
- <td>Spec-Version</td>
- <td>The version of the specification that the advisory applies to should be
- referenced here. As of this specification, the only valid value is <code>1</code>.</td>
- </tr>
-\note The following keys can be specified more than once.
- <tr>
- <td>Affected</td>
- <td>A string of one dependency atom or two ranged dependency atoms. When two
- dependency atoms are given, their intersection must not describe and empty
- set of packages.</td>
- </tr>
- <tr>
- <td>Bug-Id</td>
- <td>Identifier of a bug report that is associated with this advisory.\n
- Must be in format <code>DISTRO#YY</code>, where <code>DISTRO</code> is a unique string
- describing the distribution that the bug report is filed against and <code>YY</code>
- is the bug's local identifier.
- There is no restriction on the values of <code>DISTRO</code> besides the uniqueness,
- but each used distribution identifier should be listed along a short
- description and/or URL of the associated bug tracker in the text file
- ${repo}/metadata/security/bugtracker
-\endcode </td>
- </tr>
- <tr>
- <td>CVE</td>
- <td>A string of one CVE IDs in the format <code>CVE-XXXX-XXXX</code>. Historically,
- there have been CVE references prefixed by CAN instead of CVE. These
- are explicitly permitted by this specification, but are to be treated as
- deprecated.</td>
- </tr>
- <tr>
- <td>Reference</td>
- <td>URL to a public web-based advisory, announcement or (possibly) exploit.
- Optionally, a descriptive string can be prepended.</td>
- </tr>
- <tr>
- <td>Restart</td>
- <td>The name of a service or init script that should be restarted by
- Paludis after the vulnerable package has been replaced.</td>
- </tr>
- <tr>
- <td>Unaffected</td>
- <td>A string of one dependency atom or two ranged dependency atoms. When two
- dependency atoms are given, their intersection must not describe and empty
- set of packages.</td>
- </tr>
-The text body shall be separated from the aforementioned header by an empty
-line. The contents of the text body is not subject of this advisory.
-Paludis shall provide an eselect module to display advisory texts.
-\section Handling Handling
-Paludis will parse security advisories when it builds the built-in
-package set <code>security</code> or when it is called with command line option
-<code>--list-vulnerabilities</code>. The later shall support all modifiers, which are
-respected by other <code>--list</code> actions.
-All packages that match the contents of at least one <code>Affected</code> item and that
-do not match any <code>Unaffected</code> item will be treated as vulnerable. Paludis shall
-then search for a package in the same slot that matches at least one
-<code>Unaffected</code> items and does not match any <code>Affected</code> item. If several
-package versions match this criterion, Paludis shall select the highest version.