10 files changed, 83 insertions, 55 deletions
diff --git a/profiles/categories/text.xml b/profiles/categories/text.xml
index c04c1c1..81079b2 100644
--- a/profiles/categories/text.xml
+++ b/profiles/categories/text.xml
@@ -1,18 +1,22 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <guide self="profiles/categories/">
 <chapter>
-<title>Profiles <c>categories</c> File</title>
+<title>Profiles <c>categories</c> file</title>
 
 <body>
 <p>
 The <c>profiles/categories</c> file contains an asciibetically sorted list of all
-the valid categories in the portage tree. When adding a new category, remember
+the valid categories in the Gentoo repository. When adding a new category, remember
 to update and commit this file <e>before</e> making any related commits.
 </p>
 
 <p>
+Please consult the gentoo-dev mailing list before adding a new category.
+</p>
+
+<p>
 The <c>categories</c> file is a straight list. For descriptions, see <uri
-link="::ebuild-writing/misc-files/metadata/#Category Metadata"/>.
+link="::ebuild-writing/misc-files/metadata/#Category metadata"/>.
 </p>
 </body>
 
diff --git a/profiles/info_files/text.xml b/profiles/info_files/text.xml
index ae68b30..22f9cd2 100644
--- a/profiles/info_files/text.xml
+++ b/profiles/info_files/text.xml
@@ -1,7 +1,7 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <guide self="profiles/info_files/">
 <chapter>
-<title>Profiles <c>info_</c> Files</title>
+<title>Profiles <c>info_</c> files</title>
 <body>
 
 <p>
diff --git a/profiles/make.defaults/text.xml b/profiles/make.defaults/text.xml
index 15ea2c6..18221d4 100644
--- a/profiles/make.defaults/text.xml
+++ b/profiles/make.defaults/text.xml
@@ -1,15 +1,16 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <guide self="profiles/make.defaults/">
 <chapter>
-<title>Profiles <c>make.defaults</c> File</title>
+<title>Profiles <c>make.defaults</c> file</title>
 <body>
 
 <p>
-The <c>make.defaults</c> file in <c>profiles/</c> provides a minimal set of defaults
-for the kinds of values which may be set in <c>make.conf</c> (<c>CFLAGS</c>, <c>USE</c>,
-<c>FEATURES</c> etc) along with certain control variables (eg <c>USE_EXPAND</c>).
-These values can further be refined by additional <c>make.defaults</c> files in
-subprofiles.
+The <c>make.defaults</c> file in <c>profiles/</c> provides a minimal set
+of defaults for the kinds of values which may be set in
+<c><uri link="::eclass-reference/make.conf/"/></c> (<c>CFLAGS</c>,
+<c>USE</c>, <c>FEATURES</c> etc.) along with certain control variables
+(e.g. <c>USE_EXPAND</c>). These values can further be refined by additional
+<c>make.defaults</c> files in subprofiles.
 </p>
 
 <p>
diff --git a/profiles/package.mask/text.xml b/profiles/package.mask/text.xml
index ef57b28..9b6bc1d 100644
--- a/profiles/package.mask/text.xml
+++ b/profiles/package.mask/text.xml
@@ -1,14 +1,42 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <guide self="profiles/package.mask/">
 <chapter>
-<title>Profiles <c>package.mask</c> File</title>
+<title>Profiles <c>package.mask</c> file</title>
 <body>
 
 <p>
-The <c>package.mask</c> file can be used to hard mask packages or certain versions
-of packages. This is often used when adding certain experimental (either in
-ebuild or upstream terms) packages to the tree. The format is described in
-<c>man portage</c>.
+The <c>package.mask</c> file can be used to hard mask packages or
+certain versions of packages that should not be merged by users.
+This is often used when adding certain experimental (either in ebuild
+or upstream terms) packages to the tree, or to prevent merging of
+packages that are broken or break something else. Every entry should
+have a comment detailing the specific reason for the mask. The format
+of the <c>package.mask</c> file is described in <c>man portage</c>.
+</p>
+
+<p>
+Development or unstable (per upstream declaration/categorization) versions of
+packages should usually be masked in <c>package.mask</c>. Upstreams may not
+deem such releases to be ready for general distribution (or safe to use), or
+may not be expecting bug reports from the wider userbase yet. The default
+should generally be to mask such versions, but it is acceptable to not mask
+in some circumstances <d/> e.g. upstream make very infrequent releases, the
+changes are safe (reviewed by the Gentoo maintainer), or perhaps other
+distributions are shipping the same new version. As an alternative to a
+development version, you may also consider backporting required upstream fixes
+to the released version.
+</p>
+
+<p>
+Overall, masking something and unmasking if it turns out to be stable is
+safer (and leads to a better user experience) than the inverse (pushing
+unmasked and breakage occurring).
+</p>
+
+<p>
+Entries are added chronologically <d/> that is, newer entries
+should be placed towards the top of the file, underneath any initial
+header comment block.
 </p>
 
 <p>
diff --git a/profiles/packages/text.xml b/profiles/packages/text.xml
index b8215f7..3ae80e4 100644
--- a/profiles/packages/text.xml
+++ b/profiles/packages/text.xml
@@ -1,12 +1,12 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <guide self="profiles/packages/">
 <chapter>
-<title>Profiles <c>packages</c> File</title>
+<title>Profiles <c>packages</c> file</title>
 <body>
 
 <p>
 The <c>packages</c> file in <c>profiles/</c> controls the packages pulled in by the
-<c>system</c> target. The <c>base/packages</c> file must not be modified without
+<c>@system</c> set. The <c>base/packages</c> file must not be modified without
 discussion on the <c>gentoo-dev</c> list; subprofile overrides are up to the
 relevant arch teams.
 </p>
diff --git a/profiles/profiles.desc/text.xml b/profiles/profiles.desc/text.xml
deleted file mode 100644
index 16dc52a..0000000
--- a/profiles/profiles.desc/text.xml
+++ /dev/null
@@ -1,14 +0,0 @@
-<?xml version="1.0"?>
-<guide self="profiles/profiles.desc/">
-<chapter>
-<title>Profiles <c>profiles.desc</c> File</title>
-<body>
-
-<todo>
-Find someone who knows exactly what this file's really used for with
-current portage versions and what is and isn't allowed.
-</todo>
-
-</body>
-</chapter>
-</guide>
diff --git a/profiles/text.xml b/profiles/text.xml
index 4db23c6..cf71673 100644
--- a/profiles/text.xml
+++ b/profiles/text.xml
@@ -1,12 +1,18 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <guide self="profiles/">
 <chapter>
 <title>Profiles</title>
 
 <body>
 <p>
-This section provides details on the <c>profiles/</c> directory. All of these files
-are also documented in <c>man portage</c>.
+This section provides details on the <c>profiles/</c> directory. All of these
+files are also documented in <c>man portage</c>, but the canonical reference
+for profiles is within
+<uri link="https://projects.gentoo.org/pms/8/pms.html#x1-320004.4">PMS</uri>.
+</p>
+
+<p>
+Portage-specific behaviour must not be relied upon in the repository.
 </p>
 </body>
 
@@ -20,9 +26,9 @@ are also documented in <c>man portage</c>.
 
 <include href="categories/"/>
 <include href="info_files/"/>
+<include href="make.defaults/"/>
 <include href="package.mask/"/>
 <include href="packages/"/>
-<include href="profiles.desc/"/>
 <include href="updates/"/>
 <include href="use.desc/"/>
 <include href="use.mask/"/>
diff --git a/profiles/updates/text.xml b/profiles/updates/text.xml
index ae859e4..6e44507 100644
--- a/profiles/updates/text.xml
+++ b/profiles/updates/text.xml
@@ -1,7 +1,7 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <guide self="profiles/updates/">
 <chapter>
-<title>Profiles <c>updates/</c> Directory</title>
+<title>Profiles <c>updates/</c> directory</title>
 <body>
 
 <p>
@@ -36,10 +36,11 @@ the actual changes to the package have to be done manually.
   </tr>
   <tr>
     <ti>
-      <c>slotmove atom oldslot newslot</c>
+      <c>slotmove spec oldslot newslot</c>
     </ti>
     <ti>
-      Indicates that the atom specified has changed slots.
+      Indicates that the package matching dependency specification <c>spec</c>
+      has changed slots.
     </ti>
   </tr>
 </table>
diff --git a/profiles/use.desc/text.xml b/profiles/use.desc/text.xml
index 30c3a41..0a4e9a3 100644
--- a/profiles/use.desc/text.xml
+++ b/profiles/use.desc/text.xml
@@ -1,7 +1,7 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <guide self="profiles/use.desc/">
 <chapter>
-<title>Profiles <c>use.desc</c> and <c>use.local.desc</c> Files</title>
+<title>Profiles <c>use.desc</c> and <c>use.local.desc</c> files</title>
 <body>
 
 <p>
@@ -14,7 +14,7 @@ discussion on the <c>gentoo-dev</c> list.
 The <c>metadata.xml</c> file on each ebuild category contains a list of the local
 <c>USE</c> flags, together with short description for the package in the said category.
 More information about the <c>metadata.xml</c> file can be found
-<uri link="ebuild-writing/misc-files/metadata/index.html">here.</uri>
+<uri link="::ebuild-writing/misc-files/metadata/">here.</uri>
 </p>
 
 <note>
@@ -26,7 +26,7 @@ so you must never edit it directly.
 Having a small number of packages using identically named local <c>USE</c> flags is
 allowed. If the number starts to grow substantially, it may be worth proposing
 that the flag becomes a global <d /> see
-<uri link="::general-concepts/use-flags#Local and Global USE Flags"/>.
+<uri link="::general-concepts/use-flags/#Local and global USE flags"/>.
 </p>
 
 <p>
diff --git a/profiles/use.mask/text.xml b/profiles/use.mask/text.xml
index be6242f..543d439 100644
--- a/profiles/use.mask/text.xml
+++ b/profiles/use.mask/text.xml
@@ -1,7 +1,7 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <guide self="profiles/use.mask/">
 <chapter>
-<title>Profiles <c>use.mask</c> File</title>
+<title>Profiles <c>use.mask</c> file</title>
 <body>
 
 <p>
@@ -11,9 +11,9 @@ particular profile. This can be useful for various reasons:
 
 <ul>
   <li>
-    Masking hardware-specific feature flags. For example, <c>mmx</c> and <c>sse</c> are
-    only available on x86, <c>altivec</c> is only available on <c>ppc</c> and <c>vis</c> is
-    only available on sparc v9.
+    Masking hardware-specific feature flags. For example, <c>mmx</c> and
+    <c>sse</c> are only available on <c>x86</c>, <c>altivec</c> is only
+    available on <c>ppc</c> and <c>vis</c> is only available on <c>sparc</c> v9.
   </li>
   <li>
     Disabling unavailable soft dependencies. A simple hypothetical example <d /> say
@@ -32,11 +32,13 @@ defined purpose.
 </p>
 
 <p>
-Updates to <c>use.mask</c> should be handled via the relevant arch team.
+Updates to <c>use.mask</c> should be handled via the relevant arch team. Any
+additions are sorted chronologically, starting at the top of the file
+(underneath any comment header blocks).
 </p>
 
 <p>
-See <uri link="::general-concepts/use-flags/#noblah USE Flags"/> for more discussion.
+See <uri link="::general-concepts/use-flags/#noblah USE flags"/> for more discussion.
 </p>
 
 </body>