| Date: | Tue, 17 Oct 2017 13:43:32 +0000 |
| From: | stephen@isc.org |
| Subject: | Documentation issues in 9.12.0b1 |
| To: | bind9-public@isc.org |
These are the comments from the QA review of the documentation associated with 9.12.0b1. (Only documentation relevant to this release was examined - a review of the entire ARM was out of scope.)
There are a number of minor issues. None are serious enough to warrant a respin of the 9.12.0b1 tarballs, but they should be fixed before the final release.
Numbers in parentheses before each comment are line numbers in the file.
README
===
(59) ISC's ticketing system is now publicly available. The first sentence of this paragraph should be changed.
(79) Details on ISC's public git repository can be found at http://www.isc.org/git - the repository itself is not there.
(80) Unless we have set up the BIND GitHub repository by the time we release 9.12.0 final, the reference to the GitHub repository should be deleted.
(88) The semicolon should immediately follow the last word on the line, not start the next line.
(106) 'max-journal-size default' should be in quotes.
(108) This mention of refactoring seems to duplicate the first point in the section so perhaps should be deleted. If it is retained, it should be the second item in the list (so keeping all the items about refactoring together).
(121) Line should end with a period.
(131) We no longer support Windows XP. Following #46265, it seems that we also no longer support Windows 2003, so this should be mentioned as well.
(148/149) I think it makes more sense for CFLAGS to be on the first line of the explanation, not the middle line. Ditto for STD_CINCLUDES on the next line.
(189-213) "specify the prefix with --option=/prefix" is confusing when read in conjunction a description of --prefix on lines 236 onwards. Would not "specify the location with --option=<location>" be better?
(215) s/you must have/you must have installed/
(219) Python might well require the argparse and ply modules, but basic BIND does not. Rather than say "Python", say the component of BIND that requires these (dnssec-keymgr?).
(253) s/by by/by/
(254) s/ifconfig.sh up/ifconfig.sh (passing 'up' as the only parameter)/
(288 -308) List items should terminate with a period.
(general) For future versions of this file, I'd suggest underlining the section headers. At the moment, they don't stand out: they are single lines and some of them are amongst a set of paragraphs each of one or two lines long.
(general) This is a text file, so I'd suggest putting commands in quotes (e.g. line 262:
s/then run make test or make unit/then run "make test" or "make unit"/).
RELEASE-NOTES-bind-9.12.0b1.txt
===
(5) The version should be 9.12.0b1, not 9.12.0 (although the version is correct for the final release).
(29) Should that not read "This will not affect anyone who is using (and possibly modifying) BIND without redistributing it."?
(38) Following #46265, it seems that we also no longer support Windows 2003, so this should be mentioned as well.
(53) The cache has been removed, but the acache-enable and acache-cleaning-interval options have been deprecated? Does this mean that they are still accepted in the configuration file but no longer have an effect? If so, this should be stated.
(60) additional-from-cache and additional-from-auth have been deprecated. With reference to the previous comment, does this mean they would (but will be removed in a future release) or that they no longer have an effect but are retained for configuration file compatibility?
(95) I don't think we need a new paragraph here.
(142) s/series of nsupdate/series of nsupdate commands/
(145) s/accepts/accept/
(214) This is not clear: under what circumstances are EDNS key tag options verified and printed?
(225) We have added the new-zones-directory keyword. If not implemented in 9.12.0, a future version of BIND 9 should check the directory pointed to by new-zones-directory (if specified) is writable.
(280) The fix for the TSIG problem was not introduced in 9.12, it was fixed in 9.11.1-P3 (and related releases). This item should be removed from the list.
RELEASE-NOTES-bind-9.12.0b1.pdf
===
Content has been assumed to be the same as the .txt file, so only the formatting was checked.
New Features/"nsec3hash -r": the word NSEC3PARAM extends into the right-hand margin instead of triggering a new line.
Bv9ARM.pdf
===
(Page 62) In the description of print-time, the values "yes" and "no" in the paragraph should be in the same font as the other options; at the moment they are in bold.
(Page 79) In the description of new-zones-directory, we need to add the sentence "This directory must be writable by the effective user ID of the named process." In addition, if the directory is a relative pathname specification, is it relative to the working directory? If so, that should be stated.
(Page 87) minimal-responses: the release notes say that the default is "yes", the ARM says that the default is "no-auth". This needs to be resolved.
(Page 89) documents the option serve-stale-enable. This is wrong - the option is called stale-answer-enable.
(Page 85) The documentation for stale-answer-ttl says that for stale answers to be returned, max-stale-ttl must be set non-zero and the feature must not have been disabled through rndc. As the feature can be disabled by not specifying stale-answer-enable in the configuration file (or specifying it with a value of "no"), change "feature must not have been disabled through rndc" to "the feature must have been enabled (either by specifying "stale-answer-enable yes" in the configuration file or via rndc)."
man.dnssec-signzone.html
===
The release notes say that " dnssec-signzone -S can now add or remove synchronization records", but the entry for -S in the man page makes no mention of this.