From 6f0701b22e97e846b82566876ad3415136027075 Mon Sep 17 00:00:00 2001
From: christos <christos@NetBSD.org>
Date: Sun, 6 Jun 2004 06:15:45 +0000
Subject: [PATCH] Explain what xstr can and cannot do, and why it is not useful
 these days.

---
 usr.bin/xstr/xstr.1 | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/usr.bin/xstr/xstr.1 b/usr.bin/xstr/xstr.1
index fb6f0278e927..e1b609d9be13 100644
--- a/usr.bin/xstr/xstr.1
+++ b/usr.bin/xstr/xstr.1
@@ -1,4 +1,4 @@
-.\"	$NetBSD: xstr.1,v 1.11 2003/08/07 11:17:51 agc Exp $
+.\"	$NetBSD: xstr.1,v 1.12 2004/06/06 06:15:45 christos Exp $
 .\"
 .\" Copyright (c) 1980, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -160,3 +160,43 @@ but the shorter string is seen first by
 .Nm
 both strings will be placed in the data base, when just
 placing the longer one there will do.
+.Pp
+.Nm
+does not parse the file properly so it does not know not to process:
+.Bd -literal
+	char var[] = "const";
+.Ed
+into:
+.Bd -literal
+	char var[] = (&xstr[N]);
+.Ed
+.Pp
+These must be changed manually into an appropriate initialization for
+the string, or use the following ugly hack.
+.Pp
+Also,
+.Nm
+cannot initialize structures and unions that contain strings. Those can
+be fixed by changing from:
+.Bd -literal
+	struct foo {
+		int i;
+		char buf[10];
+	} = {
+		1, "foo"
+	};
+.Ed
+to:
+.Bd -literal
+	struct foo {
+		int i;
+		char buf[10];
+	} = {
+		1, { 'f', 'o', 'o', '\e0' }
+	};
+.Ed
+.Pp
+Finally,
+.Nm
+is not very useful these days because most of the string merging is done
+automatically by the compiler and the linker.