changes to documentation.

5 files changed, 67 insertions, 3 deletions

diff --git a/ChangeLog b/ChangeLog
index e570132..c81c0d4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2003-07-08  Junichi Uekawa  <dancer@debian.org>
+
+	* pbuilderrc.5: update to note about user-mode-linux quirks.
+
+	* pbuilder-uml.conf.5: note that APTCACHEHARDLINK
+
+	* Documentation/pbuilder-doc.xml: document the error for LOGNAME not defined warning, Invalid cross-device link error, and conflict against essential being a bad idea.
+
 2003-07-03  Junichi Uekawa  <dancer@debian.org>
 
 	* pbuilder-user-mode-linux.1: document that.
diff --git a/Documentation/pbuilder-doc.xml b/Documentation/pbuilder-doc.xml
index ccb35c0..8e3975e 100644
--- a/Documentation/pbuilder-doc.xml
+++ b/Documentation/pbuilder-doc.xml
@@ -472,6 +472,43 @@ export DEBIAN_BUILDGCCVER=3.2
 	<screen>deb http://www.microcomaustralia.com.au/debian/ woody main</screen>
       </para>
     </sect1>
+    <sect1 id="LOGNAME">
+      <title>Warning on LOGNAME not being defined</title>
+      <para>
+	You might see a lot of warning messages when running pbuilder.
+      </para>
+      <para>
+	<screen>
+	dpkg-genchanges: warning: no utmp entry available and LOGNAME not defined; using uid of process (1234)
+	</screen>
+      </para>
+      <para>
+	It is currently safe to ignore this warning message.
+	Please report back if you find any problem with having LOGNAME unset.
+	Setting LOGNAME caused a few problems when invoking chroot.
+      </para>
+    </sect1>
+    <sect1 id="nobuildconflictessential">
+      <title>Cannot Build-conflict against an essential package</title>
+      <para>
+	pbuilder does not currently allow Build-Conflicts against 
+	essential packages.
+	It should be obvious that essential packages should not be 
+	removed from a working Debian system, and a source 
+	package should not try to force removal of such packages 
+	to people building the package.
+      </para>
+    </sect1>
+    <sect1>
+      <title>Avoiding the "ln: Invalid cross-device link" message</title>
+      <para>
+	By default, pbuilder uses hard links to manage pbuilder package cache.
+	It is not possible to make hard links across different devices; 
+	and thus this error will occur, depending on your set up.
+	If this happens, set <screen>APTCACHEHARDLINK=no</screen>
+	in your pbuilderrc file.
+      </para>
+    </sect1>
   </chapter>
   <chapter id="otheruse">
     <title>Other uses of pbuilder</title>
diff --git a/debian/changelog b/debian/changelog
index f1ad7c2..a04c466 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -2,8 +2,16 @@ pbuilder (0.76) UNRELEASED; urgency=low
 
   * Read config file in pbuilder-user-mode-linux specified by 
     --configfile.
-
- -- Junichi Uekawa <dancer@debian.org>  Thu,  3 Jul 2003 00:23:13 +0900
+    Should address bugs 
+  * Update documentation FAQ section.
+  - note that the warning message about LOGNAME being unset is currently safe.
+    (closes: #187924)
+  - Document that it is not a good idea to conflict against an essential 
+    package and pbuilder doesn't particularly support it. (closes: #169223)
+  - Document "Invalid cross-device link" and how to fix it (closes: #200103)
+  * Update some manual pages to reflect the changes.
+
+ -- Junichi Uekawa <dancer@debian.org>  Tue,  8 Jul 2003 22:00:19 +0900
 
 pbuilder (0.75) unstable; urgency=low
 
diff --git a/pbuilder-uml.conf.5 b/pbuilder-uml.conf.5
index 8a688df..d417ff3 100644
--- a/pbuilder-uml.conf.5
+++ b/pbuilder-uml.conf.5
@@ -68,7 +68,14 @@ will be able to return the FQDN.
 The directory where build result of pbuilder-user-mode-linux 
 is stored.
 
-.SH AUTHOR
+.SH "NOTES"
+
+It is advised to set 
+.B "APTCACHEHARDLINK"
+to no in 
+.B "pbuilderrc(5)"
+
+.SH "AUTHOR"
 Initial coding, and main maintenance is done by 
 Junichi Uekawa <dancer@debian.org>.
 
diff --git a/pbuilderrc.5 b/pbuilderrc.5
index f161689..f1f599f 100644
--- a/pbuilderrc.5
+++ b/pbuilderrc.5
@@ -135,6 +135,10 @@ Specify using hard links in apt cache handling.
 Changing this to no will disable hard linking and will
 copy the files.
 
+It is advised to set this to 
+.B "no"
+if you are using user-mode-linux.
+
 .TP
 .BI "REMOVEPACKAGES=" "lilo"
 Specify the packages to be removed on creation of