[v9_11] update README, remove FAQ

4593. [doc] Update README using markdown, remove outdated FAQ file in favor of the knowledge base.

[v9_11] update README, remove FAQ
4593. [doc] Update README using markdown, remove outdated FAQ file in favor of the knowledge base.
0d7548ee · Evan Hunt · c32570b3 · 0d7548ee · c32570b3 · c32570b3
Commit 0d7548ee authored Apr 20, 2017 by Evan Hunt
18 changed files
--- a/CHANGES
+++ b/CHANGES
+4593.	[doc]		Update README using markdown, remove outdated FAQ
+			file in favor of the knowledge base.
+
 4592.	[bug]		A race condition on shutdown could trigger an
 			assertion failure in dispatch.c. [RT #43822]

@@ -12993,7 +12996,7 @@

 586.	[bug]		multiple views with the same name were fatal. [RT #516]

- 585.	[func]		dns_db_addrdataset() and and dns_rdataslab_merge()
+ 585.	[func]		dns_db_addrdataset() and dns_rdataslab_merge()
 			now support 'exact' additions in a similar manner to
 			dns_db_subtractrdataset() and dns_rdataslab_subtract().


--- a/FAQ
+++ b/FAQ
--- a/FAQ.xml
+++ b/FAQ.xml
--- a/HISTORY
+++ b/HISTORY
--- a/HISTORY.md
+++ b/HISTORY.md
--- a/Makefile.in
+++ b/Makefile.in
@@ -4,8 +4,6 @@
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.

-# $Id: Makefile.in,v 1.62 2011/09/06 04:06:37 marka Exp $
-
 srcdir =	@srcdir@
 VPATH =		@srcdir@
 top_srcdir =	@top_srcdir@
@@ -20,7 +18,7 @@ MANPAGES =	isc-config.sh.1

 HTMLPAGES =	isc-config.sh.html

-MANOBJS =	${MANPAGES} ${HTMLPAGES}
+MANOBJS =	README HISTORY OPTIONS ${MANPAGES} ${HTMLPAGES}

 @BIND9_MAKE_RULES@

@@ -91,13 +89,19 @@ test-force:
 	(test -f unit/unittest.sh && $(SHELL) unit/unittest.sh) || status=1; \
 	exit $$status

-FAQ: FAQ.xml
-	${XSLTPROC} doc/xsl/isc-docbook-text.xsl FAQ.xml | \
-	LC_ALL=C ${W3M} -T text/html -dump -cols 72 >$@.tmp
-	mv $@.tmp $@
+README: README.md
+	${PANDOC} --email-obfuscation=none -s -t html $< | \
+		${W3M} -dump -cols 75 -O ascii -T text/html > $@
+
+HISTORY: HISTORY.md
+	${PANDOC} --email-obfuscation=none -s -t html $< | \
+		${W3M} -dump -cols 75 -O ascii -T text/html > $@
+
+OPTIONS: OPTIONS.md
+	${PANDOC} --email-obfuscation=none -s -t html $< | \
+		${W3M} -dump -cols 75 -O ascii -T text/html > $@

 unit::
 	sh ${top_srcdir}/unit/unittest.sh

 clean::
-	rm -f FAQ.tmp
--- a/OPTIONS
+++ b/OPTIONS
+Setting the STD_CDEFINES environment variable before running configure can
+be used to enable certain compile-time options that are not explicitly
+defined in configure.
+
+Some of these settings are:
+
+Setting                   Description
+                          Don't ovewrite memory when allocating or freeing
+-DISC_MEM_FILL=0          it; this improves performance but makes
+                          debugging more difficult.
+                          Don't track memory allocations by file and line
+-DISC_MEM_TRACKLINES=0    number; this improves performance but makes
+                          debugging more difficult.
+-DISC_FACILITY=LOG_LOCAL0 Change the default syslog facility for named
+-DNS_CLIENT_DROPPORT=0    Disable dropping queries from particular
+                          well-known ports:
+-DCHECK_SIBLING=0         Don't check sibling glue in named-checkzone
+-DCHECK_LOCAL=0           Don't check out-of-zone addresses in
+                          named-checkzone
+-DNS_RUN_PID_DIR=0        Create default PID files in ${localstatedir}/run
+                          rather than ${localstatedir}/run/{named,lwresd}/
+                          Enable DNSSEC signature chasing support in dig.
+-DDIG_SIGCHASE=1          (Note: This feature is deprecated. Use delv
+                          instead.)
+
--- a/OPTIONS.md
+++ b/OPTIONS.md
+Setting the `STD_CDEFINES` environment variable before running `configure`
+can be used to enable certain compile-time options that are not explicitly
+defined in `configure`.
+
+Some of these settings are:
+
+|Setting                            |Description |
+|-----------------------------------|----------------------------------------|
+|`-DISC_MEM_FILL=0`|Don't ovewrite memory when allocating or freeing it; this improves performance but makes debugging more difficult.|
+|`-DISC_MEM_TRACKLINES=0`|Don't track memory allocations by file and line number; this improves performance but makes debugging more difficult.|
+|<nobr>`-DISC_FACILITY=LOG_LOCAL0`</nobr>|Change the default syslog facility for `named`|
+|`-DNS_CLIENT_DROPPORT=0`|Disable dropping queries from particular well-known ports:|
+|`-DCHECK_SIBLING=0`|Don't check sibling glue in `named-checkzone`|
+|`-DCHECK_LOCAL=0`|Don't check out-of-zone addresses in `named-checkzone`|
+|`-DNS_RUN_PID_DIR=0`|Create default PID files in `${localstatedir}/run` rather than `${localstatedir}/run/{named,lwresd}/`|
+|`-DDIG_SIGCHASE=1`|Enable DNSSEC signature chasing support in `dig`.  (Note: This feature is deprecated. Use `delv` instead.)|
+
--- a/README
+++ b/README
--- a/README.md
+++ b/README.md
--- a/configure
+++ b/configure
@@ -695,6 +695,7 @@ CURL
 DOXYGEN
 XMLLINT
 XSLTPROC
+PANDOC
 W3M
 DBLATEX
 PDFLATEX
@@ -955,6 +956,7 @@ infodir
 docdir
 oldincludedir
 includedir
+runstatedir
 localstatedir
 sharedstatedir
 sysconfdir
@@ -1110,6 +1112,7 @@ datadir='${datarootdir}'
 sysconfdir='${prefix}/etc'
 sharedstatedir='${prefix}/com'
 localstatedir='${prefix}/var'
+runstatedir='${localstatedir}/run'
 includedir='${prefix}/include'
 oldincludedir='/usr/include'
 docdir='${datarootdir}/doc/${PACKAGE_TARNAME}'
@@ -1362,6 +1365,15 @@ do
  | -silent | --silent | --silen | --sile | --sil)
    silent=yes ;;
  
+  -runstatedir | --runstatedir | --runstatedi | --runstated \
+  | --runstate | --runstat | --runsta | --runst | --runs \
+  | --run | --ru | --r)
+    ac_prev=runstatedir ;;
+  -runstatedir=* | --runstatedir=* | --runstatedi=* | --runstated=* \
+  | --runstate=* | --runstat=* | --runsta=* | --runst=* | --runs=* \
+  | --run=* | --ru=* | --r=*)
+    runstatedir=$ac_optarg ;;
+
  -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb)
    ac_prev=sbindir ;;
  -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \
@@ -1499,7 +1511,7 @@ fi
 for ac_var in	exec_prefix prefix bindir sbindir libexecdir datarootdir \
 		datadir sysconfdir sharedstatedir localstatedir includedir \
 		oldincludedir docdir infodir htmldir dvidir pdfdir psdir \
-		libdir localedir mandir
+		libdir localedir mandir runstatedir
 do
  eval ac_val=\$$ac_var
  # Remove trailing slashes.
@@ -1652,6 +1664,7 @@ Fine tuning of the installation directories:
  --sysconfdir=DIR        read-only single-machine data [PREFIX/etc]
  --sharedstatedir=DIR    modifiable architecture-independent data [PREFIX/com]
  --localstatedir=DIR     modifiable single-machine data [PREFIX/var]
+  --runstatedir=DIR       modifiable per-process data [LOCALSTATEDIR/run]
  --libdir=DIR            object code libraries [EPREFIX/lib]
  --includedir=DIR        C header files [PREFIX/include]
  --oldincludedir=DIR     C header files for non-gcc [/usr/include]
@@ -21246,6 +21259,53 @@ test -n "$W3M" || W3M="w3m"
  
  
  
+#
+# Look for pandoc
+#
+# Extract the first word of "pandoc", so it can be a program name with args.
+set dummy pandoc; 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_path_PANDOC+:} false; then :
+  $as_echo_n "(cached) " >&6
+else
+  case $PANDOC in
+  [\\/]* | ?:[\\/]*)
+  ac_cv_path_PANDOC="$PANDOC" # Let the user override the test with a path.
+  ;;
+  *)
+  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_path_PANDOC="$as_dir/$ac_word$ac_exec_ext"
+    $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
+
+  test -z "$ac_cv_path_PANDOC" && ac_cv_path_PANDOC="pandoc"
+  ;;
+esac
+fi
+PANDOC=$ac_cv_path_PANDOC
+if test -n "$PANDOC"; then
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: $PANDOC" >&5
+$as_echo "$PANDOC" >&6; }
+else
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+fi
+
+
+
+
+
 #
 # Look for xsltproc (libxslt)
 #

--- a/configure.in
+++ b/configure.in
@@ -4430,6 +4430,13 @@ AC_SUBST(DBLATEX)
 AC_PATH_PROGS(W3M, w3m, w3m)
 AC_SUBST(W3M)

+#
+# Look for pandoc
+#
+AC_PATH_PROG(PANDOC, pandoc, pandoc)
+AC_SUBST(PANDOC)
+
+
 #
 # Look for xsltproc (libxslt)
 #

--- a/doc/markdown/howto.mkd
+++ b/doc/markdown/howto.mkd
@@ -6,7 +6,7 @@
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
 --->
 ## BIND Source Access and Contributor Guidelines
-*May 8, 2014*
+*Apr 14, 2017*

 ### Contents

@@ -81,8 +81,8 @@ Suggested changes or requests for new features can be emailed to
 `bind-suggest@isc.org`.  Both bugs and suggestions are stored in the
 ticketing system used by the software engineering team at ISC.

-All submissions to the ticketing system receive an automatic response.
-Any followup email sent to the ticketing system should use the same subject
+All submissions to the ticketing system receive an automatic response.  Any
+followup email sent to the ticketing system should use the same subject
 header, so that it will be routed to the same ticket.

 Due to a large ticket backlog and an even larger quantity of incoming spam,
@@ -90,14 +90,15 @@ we are sometimes slow to respond, especially if a bug is cosmetic or if a
 feature request is vague or low in priority, but we will try at least to
 acknowledge legitimate bug reports within a week.

-The bug database is not publicly readable. Information about your
-system that you submit in bug reports will not be divulged outside ISC.
+Currently, ISC's ticketing system is not publicly readable. However, ISC
+may open it in the future. Please do not include information you consider
+to be confidential.

 ### <a name="bugs"></a>Contributing code

 BIND's [open source
 license](http://www.isc.org/downloads/software-support-policy/isc-license/)
-does not require changes to be contributed back to ISC, but this page
+not require changes to be contributed back to ISC, but this page
 includes some guidelines for those who would like to do so.

 We accept two different types of code contribution:  Code intended for
@@ -116,39 +117,40 @@ your patch introduces a new feature in BIND, please submit it to
 ISC does not require an explicit copyright assignment for patch
 contributions.  However, by submitting a patch to ISC, you implicitly
 certify that you are the author of the code, that you intend to reliquish
-exclusive copyright, and that you grant permission to publish your
-work under the
-[ISC license](http://www.isc.org/downloads/software-support-policy/isc-license/).
+exclusive copyright, and that you grant permission to publish your work
+under the
+[Mozilla Public License 2.0](http://www.isc.org/downloads/software-support-policy/isc-license/)
+for BIND 9.11 and higher, and the
+[ISC License](http://www.isc.org/downloads/software-support-policy/isc-license/)
+for BIND 9.10 and earlier.

 Patches should be submitted as diffs against a specific version of BIND --
 preferably the current top of the `master` branch.  Diffs may be
 generated using either `git format-patch` or `git diff`.

-Those wanting to write code for BIND may be interested
-in the [developer information](dev.html) page, which includes
-information about BIND design and coding practices, including
-discussion of internal APIs and overall system architecture.
-(This is a work in progress, and still quite preliminary.)
+Those wanting to write code for BIND may be interested in the [developer
+information](dev.md) page, which includes information about BIND design and
+coding practices, including discussion of internal APIs and overall system
+architecture.  (This is a work in progress, and still quite preliminary.)

-Every patch submitted will be reviewed by ISC engineers following
-our [code review process](dev.html#reviews) before it is merged.
+Every patch submitted will be reviewed by ISC engineers following our [code
+review process](dev.md#reviews) before it is merged.

-It may take considerable time to review patch submissions, especially
-if they don't meet ISC style and quality guidelines.  If the patch
-is a good idea, we can and will do additional work to bring them up
-to par, but if we're busy with other work, it may take us a long
-time to get to it.
+It may take considerable time to review patch submissions, especially if
+they don't meet ISC style and quality guidelines.  If the patch is a good
+idea, we can and will do additional work to bring them up to par, but if
+we're busy with other work, it may take us a long time to get to it.

 To ensure your patch is acted on as promptly as possible, please:

-* Try to adhere to the [BIND 9 coding style](style.html).
+* Try to adhere to the [BIND 9 coding style](style.md).
 * Run `make` `check` to ensure your change hasn't caused any
  functional regressions.
 * Document your work, both in the patch itself and in the
  accompanying email.
 * In patches that make non-trivial functional changes, include system
  tests if possible; when introducing or substantially altering a
-  library API, include unit tests. See [Testing](dev.html#testing)
+  library API, include unit tests. See [Testing](dev.md#testing)
  for more information.

 ##### Changes to `configure`
@@ -195,5 +197,5 @@ testers including `queryperf` and `perftcpdns`; and drivers and modules for
 DLZ.

 If you have code with a BSD-compatible license that you would like us to
-includ in `contrib`, please send it to `bind-suggest@isc.org`, with
+include in `contrib`, please send it to `bind-suggest@isc.org`, with
 "`[CONTRIB]`" in the subject header.
--- a/doc/markdown/dev.mkd
+++ b/doc/markdown/dev.mkd
@@ -27,7 +27,7 @@
    * [Adding a new RR type](#rrtype)
    * [Task and timer model](#tasks)

-### <a name="reviews"</a>The code review process
+### <a name="reviews"></a>The code review process

 Every line of code comitted to BIND has been reviewed by ISC engineers
 first.
@@ -334,8 +334,8 @@ creating a memory context.  Similar functions `dns_test_begin()` and

 #### Namespace

-See the [namespace](style.html#public_namespace) discussion in the
-[BIND coding style](style.html) document.
+See the [namespace](style.md#public_namespace) discussion in the
+[BIND coding style](style.md) document.

 #### <a name="dbc"></a>Design by contract

@@ -520,17 +520,17 @@ as part of the 'used' subregion:
 Several functions are provided for both reading and writing
 to the buffer:

-* `isc_buffer_getuint8`: Read and return an 8-bit unsigned integer
-* `isc_buffer_putuint8`: Write an 8-bit unsigned integer to a buffer
+* `isc_buffer_getuint8()`: Read and return an 8-bit unsigned integer
+* `isc_buffer_putuint8()`: Write an 8-bit unsigned integer to a buffer

-* `isc_buffer_getuint16`: Read a 16-bit unsigned integer in
+* `isc_buffer_getuint16()`: Read a 16-bit unsigned integer in
  network byte order, convert to host byte order, and return it
-* `isc_buffer_putuint16`: Convert an unsigned 16-bit integer from
+* `isc_buffer_putuint16()`: Convert an unsigned 16-bit integer from
  host to network byte order and write it to a buffer.

-* `isc_buffer_getuint32`: Read a 32-bit unsigned integer in
+* `isc_buffer_getuint32()`: Read a 32-bit unsigned integer in
  network byte order, convert to host byte order, and return it
-* `isc_buffer_putuint32`: Convert an unsigned 32-bit integer from
+* `isc_buffer_putuint32()`: Convert an unsigned 32-bit integer from
  host to network byte order and write it to a buffer.

 * `isc_buffer_putstr()`: Copy a null-terminated string into a buffer

--- a/doc/markdown/style.mkd
+++ b/doc/markdown/style.mkd
@@ -370,7 +370,7 @@ be ambiguous.
 #### Clear Success or Failure

 A function should report success or failure, and do so accurately.  It
-should never fail silently.  Use of [design by contract](dev.html#dbc)
+should never fail silently.  Use of [design by contract](dev.md#dbc)
 can help here.

 When a function is designed to return results to the caller by assigning
@@ -380,8 +380,8 @@ fails.  A `REQUIRE()` statement should be used to ensure that the pointer
 is in a sane state when the function is called.

 The `isc_result_t` is provided for use by result codes.  See the
-[results](dev.html#results) section of the [developer
-information](dev.html) page for more details.
+[results](dev.md#results) section of the [developer
+information](dev.md) page for more details.

 #### Testing Bits

@@ -648,7 +648,7 @@ from a source with a BSD-compatible license).

 BIND provides portable internal versions of many common library calls.
 Some are designed to ensure that library calls have standardized
-[ISC result codes](dev.html#results) instead of using potentially
+[ISC result codes](dev.md#results) instead of using potentially
 nonwportable `errno` values; these include the file operations
 in `isc_file` and `isc_stdio`.  Others, such as `isc_tm_strptime()`,
 are needed to ensure consistent cross-platform behavior.
@@ -668,7 +668,7 @@ in separate files, such as `lib/isc/unix/file.c` and `lib/isc/win32/file.c`.
 #### Log messages

 Error and warning messages should be logged through the [logging
-system](dev.html#logging).  Debugging `printf`s may be used during
+system](dev.md#logging).  Debugging `printf`s may be used during
 development, but must be removed when the debugging is finished.

 Log messages do not start with a capital letter, nor do they end in a

--- a/doc/markdown/.gitignore
+++ b/doc/markdown/.gitignore
-*.html
--- a/doc/markdown/Makefile
+++ b/doc/markdown/Makefile
-# Copyright (C) 2014, 2016  Internet Systems Consortium, Inc. ("ISC")
-#
-# This Source Code Form is subject to the terms of the Mozilla Public
-# License, v. 2.0. If a copy of the MPL was not distributed with this
-# file, You can obtain one at http://mozilla.org/MPL/2.0/.
-
-all: style.html howto.html dev.html
-
-%.html: %.mkd
-	markdown $< > $@
-
-clean:
-	rm style.html howto.html dev.html
--- a/make/rules.in
+++ b/make/rules.in
@@ -307,6 +307,7 @@ LATEX =			@LATEX@
 PDFLATEX =		@PDFLATEX@
 DBLATEX =		@DBLATEX@
 W3M =			@W3M@
+PANDOC =		@PANDOC@

 ###
 ### Script language program used to create internal symbol tables