libctf: add CTF format specification

It's been a long time since most of this was written: it's long past
time to put it in the binutils source tree.  It's believed correct and
complete insofar as it goes: it documents format v3 (the current
version) but not the libctf API or any earlier versions.  (The
earlier versions can be read by libctf but not generated by it, and you
are highly unlikely ever to see an example of any of them.)

libctf/ChangeLog
2021-11-08  Nick Alcock  <nick.alcock@oracle.com>

	* doc/ctf-spec.texi: New file.
	* configure.ac (MAKEINFO): Add.
	(BUILD_INFO): Likewise.
	(AC_CONFIG_FILES) [doc/Makefile]: Add.
	* Makefile.am [BUILD_INFO] (SUBDIRS): Add doc/.
	* doc/Makefile.am: New file.
	* doc/Makefile.in: Likewise.
	* configure: Regenerated.
	* Makefile.in: Likewise.

libctf/configure

@@ -642,6 +642,8 @@ TCL_TRY_TRUE
 EXPECT
 CTF_LIBADD
 SHARED_LDFLAGS
+BUILD_INFO_FALSE
+BUILD_INFO_TRUE
 NEED_CTF_QSORT_R_FALSE
 NEED_CTF_QSORT_R_TRUE
 ENABLE_LIBCTF_HASH_DEBUGGING_FALSE
@@ -11588,7 +11590,7 @@ else
   lt_dlunknown=0; lt_dlno_uscore=1; lt_dlneed_uscore=2
   lt_status=$lt_dlunknown
   cat > conftest.$ac_ext <<_LT_EOF
-#line 11591 "configure"
+#line 11593 "configure"
 #include "confdefs.h"
 
 #if HAVE_DLFCN_H
@@ -11694,7 +11696,7 @@ else
   lt_dlunknown=0; lt_dlno_uscore=1; lt_dlneed_uscore=2
   lt_status=$lt_dlunknown
   cat > conftest.$ac_ext <<_LT_EOF
-#line 11697 "configure"
+#line 11699 "configure"
 #include "confdefs.h"
 
 #if HAVE_DLFCN_H
@@ -13407,6 +13409,81 @@ $as_echo "#define HAVE_O_CLOEXEC 1" >>confdefs.h
 
 fi
 
+build_info=
+makeinfo_too_old=
+for ac_prog in makeinfo
+do
+  # Extract the first word of "$ac_prog", so it can be a program name with args.
+set dummy $ac_prog; ac_word=$2
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
+$as_echo_n "checking for $ac_word... " >&6; }
+if ${ac_cv_prog_MAKEINFO+:} false; then :
+  $as_echo_n "(cached) " >&6
+else
+  if test -n "$MAKEINFO"; then
+  ac_cv_prog_MAKEINFO="$MAKEINFO" # Let the user override the test.
+else
+as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
+for as_dir in $PATH
+do
+  IFS=$as_save_IFS
+  test -z "$as_dir" && as_dir=.
+    for ac_exec_ext in '' $ac_executable_extensions; do
+  if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
+    ac_cv_prog_MAKEINFO="$ac_prog"
+    $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
+    break 2
+  fi
+done
+  done
+IFS=$as_save_IFS
+
+fi
+fi
+MAKEINFO=$ac_cv_prog_MAKEINFO
+if test -n "$MAKEINFO"; then
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: $MAKEINFO" >&5
+$as_echo "$MAKEINFO" >&6; }
+else
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+fi
+
+
+  test -n "$MAKEINFO" && break
+done
+test -n "$MAKEINFO" || MAKEINFO="$MISSING makeinfo"
+
+case " $build_configdirs " in
+  *" texinfo "*) MAKEINFO='$$r/$(BUILD_SUBDIR)/texinfo/makeinfo/makeinfo' ;;
+esac
+
+    # We require texinfo to be 6.3 or later, for a working synindex
+    # and validatemenus: otherwise we fall back to /bin/true.
+    if ${MAKEINFO} --version \
+       | egrep 'texinfo[^0-9]*(6\.[3-9]|[7-9][0-9])' >/dev/null 2>&1; then
+      build_info=yes
+    else
+        build_info=
+        makeinfo_too_old=t
+    fi
+
+if test -n "$makeinfo_too_old"; then
+    { $as_echo "$as_me:${as_lineno-$LINENO}: WARNING:
+*** Makeinfo is too old. Info documentation will not be built." >&5
+$as_echo "$as_me: WARNING:
+*** Makeinfo is too old. Info documentation will not be built." >&2;}
+fi
+
+ if test "${build_info}" = yes; then
+  BUILD_INFO_TRUE=
+  BUILD_INFO_FALSE='#'
+else
+  BUILD_INFO_TRUE='#'
+  BUILD_INFO_FALSE=
+fi
+
+
 CTF_LIBADD="-L`pwd`/../libiberty -liberty"
 SHARED_LDFLAGS=
 
@@ -13569,7 +13646,7 @@ fi
 
 
 
-ac_config_files="$ac_config_files Makefile"
+ac_config_files="$ac_config_files Makefile doc/Makefile"
 
 ac_config_headers="$ac_config_headers config.h"
 
@@ -13723,6 +13800,10 @@ if test -z "${NEED_CTF_QSORT_R_TRUE}" && test -z "${NEED_CTF_QSORT_R_FALSE}"; th
   as_fn_error $? "conditional \"NEED_CTF_QSORT_R\" was never defined.
 Usually this means the macro was only invoked conditionally." "$LINENO" 5
 fi
+if test -z "${BUILD_INFO_TRUE}" && test -z "${BUILD_INFO_FALSE}"; then
+  as_fn_error $? "conditional \"BUILD_INFO\" was never defined.
+Usually this means the macro was only invoked conditionally." "$LINENO" 5
+fi
 if test -z "${TCL_TRY_TRUE}" && test -z "${TCL_TRY_FALSE}"; then
   as_fn_error $? "conditional \"TCL_TRY\" was never defined.
 Usually this means the macro was only invoked conditionally." "$LINENO" 5
@@ -14582,6 +14663,7 @@ do
     "depfiles") CONFIG_COMMANDS="$CONFIG_COMMANDS depfiles" ;;
     "libtool") CONFIG_COMMANDS="$CONFIG_COMMANDS libtool" ;;
     "Makefile") CONFIG_FILES="$CONFIG_FILES Makefile" ;;
+    "doc/Makefile") CONFIG_FILES="$CONFIG_FILES doc/Makefile" ;;
     "config.h") CONFIG_HEADERS="$CONFIG_HEADERS config.h" ;;
 
   *) as_fn_error $? "invalid argument: \`$ac_config_target'" "$LINENO" 5;;