diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index d75811c81b..c84ad06a35 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -1,11 +1,11 @@ EXTRA_DIST = bind10-guide.css -EXTRA_DIST += bind10-guide.html bind10-messages.html -EXTRA_DIST += bind10-guide.xml +EXTRA_DIST += bind10-guide.xml bind10-guide.html +EXTRA_DIST += bind10-messages.xml bind10-messages.html # This is not a "man" manual, but reuse this for now for docbook. if ENABLE_MAN -.PHONY: bind10-messages.html +.PHONY: bind10-messages.xml bind10-guide.html: bind10-guide.xml xsltproc --novalid --xinclude --nonet \ @@ -15,8 +15,16 @@ bind10-guide.html: bind10-guide.xml http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl \ $(srcdir)/bind10-guide.xml +bind10-messages.html: bind10-messages.xml + xsltproc --novalid --xinclude --nonet \ + --path $(top_builddir)/doc \ + -o $@ \ + --stringparam html.stylesheet $(srcdir)/bind10-guide.css \ + http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl \ + $(srcdir)/bind10-messages.xml + # So many dependencies that it's easiest just to regenerate it every time -bind10-messages.html: +bind10-messages.xml: $(PYTHON) $(top_srcdir)/tools/system_messages.py -o $@ $(top_srcdir) endif diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml index 2294750bee..60989e68b9 100644 --- a/doc/guide/bind10-guide.xml +++ b/doc/guide/bind10-guide.xml @@ -1480,7 +1480,7 @@ then change those defaults with config set Resolver/forward_addresses[0]/address The message identification. Every message in BIND-10 has a unique identification, which can be used as an index into the - BIND10 Messages Manual + BIND10 Messages Manual from which more information can be obtained. diff --git a/tools/system_messages.py b/tools/system_messages.py index c1c8556499..cf9bfbac31 100644 --- a/tools/system_messages.py +++ b/tools/system_messages.py @@ -51,33 +51,91 @@ dictionary = {} # illustration to make the structure clearer.) The text of these section is: # Header - this is output before anything else. -SEC_HEADER = """ - -BIND 10 System Messages - - - -

BIND 10 System Messages

-

+SEC_HEADER=""" + + +%version; +]> + + + + + BIND 10 Messages Manual + + + 2011Internet Systems Consortium, Inc. + + + + BIND 10 is a Domain Name System (DNS) suite managed by + Internet Systems Consortium (ISC). It includes DNS libraries + and modular components for controlling authoritative and + recursive DNS servers. + + + This is the messages manual for BIND 10 version &__VERSION__;. + The most up-to-date version of this document, along with + other documents for BIND 10, can be found at + . + + + + This is the messages manual for BIND 10 version + &__VERSION__;. + + + + Introduction + + This document lists each messages that can be logged by the + programs in the BIND 10 package. Each entry in this manual + is of the form: + IDENTIFICATION, message-text + ... where "IDENTIFICATION" is the message identification included + in each message logged and "message-text" is the accompanying + message text. "message-text" may include placeholders of the + form "%1", "%2" etc.; these parameters are replaced by relevant + values when the message is logged. + + + Each entry is also accompanied by a description giving more + information about the circumstances that result in the message + being logged. + + + + + BIND 10 Messages + + """ # This is output once for each message. The string contains substitution # tokens: $I is replaced by the message identification, $T by the message text, # and $D by the message description. -SEC_MESSAGE = """$I, $T
-$D""" +SEC_MESSAGE = """ +$I, $T + +$D + +""" # A description may contain blank lines intended to separate paragraphs. If so, # each blank line is replaced by the following. -SEC_BLANK = "

" +SEC_BLANK = "" # The separator is copied to the output verbatim after each message except # the last. -SEC_SEPARATOR = "

" +SEC_SEPARATOR = "" # The trailier is copied to the output verbatim after the last message. -SEC_TRAILER = """ -""" +SEC_TRAILER = """ + + + +""" def reportError(filename, what): @@ -89,21 +147,14 @@ def reportError(filename, what): -# Printing functions -def printHeader(): - print(SEC_HEADER) - -def printSeparator(): - print(SEC_SEPARATOR) - -def printMessage(msgid): - m1 = SEC_MESSAGE.replace("$I", msgid) - m2 = m1.replace("$T", dictionary[msgid]['text']) - m3 = m2.replace("$D", dictionary[msgid]['description']) - print(m3) - -def printTrailer(): - print(SEC_TRAILER) +def replaceTag(string): + """Replaces the '<' and '>' in text about to be inserted into the template + sections above with < and > to avoid problems with message text + being interpreted as XML text. + """ + string1 = string.replace("<", "<") + string2 = string1.replace(">", ">") + return string2 @@ -122,6 +173,38 @@ def replaceBlankLines(lines): +# Printing functions +def printHeader(): + print(SEC_HEADER) + +def printSeparator(): + print(SEC_SEPARATOR) + +def printMessage(msgid): + # In the message ID, replace "<" and ">" with XML-safe versions and + # substitute into the data. + m1 = SEC_MESSAGE.replace("$I", replaceTag(msgid)) + + # Do the same for the message text. + m2 = m1.replace("$T", replaceTag(dictionary[msgid]['text'])) + + # Do the same for the description then replace blank lines with the + # specified separator. (We do this in that order to avoid replacing + # the "<" and ">" in the XML tags in the separator.) + desc1 = [replaceTag(l) for l in dictionary[msgid]['description']] + desc2 = replaceBlankLines(desc1) + + # Join the lines together to form a single string and insert into + # current text. + m3 = m2.replace("$D", "\n".join(desc2)) + + print(m3) + +def printTrailer(): + print(SEC_TRAILER) + + + def removeEmptyLeadingTrailing(lines): """Removes leading and trailing empty lines. @@ -190,17 +273,12 @@ def addToDictionary(msgid, msgtext, desc, filename): i = i + 1 msgid = msgid + " (" + str(i) + ")" - # Remove leading and trailing blank lines, and replace embedded blanks - # with the blank section element. - modified_desc = replaceBlankLines(removeEmptyLeadingTrailing(desc)) - - # Put everything in a sub-dictionary that is added to the main one. At - # this point, for ease of subsequent processing the description lines are - # concatenated together to form a single string, the lines being separated - # by a newline. + # Remove leading and trailing blank lines in the description, then + # add everything into a subdictionary which is then added to the main + # one. details = {} details['text'] = msgtext - details['description'] = "\n".join(modified_desc) + details['description'] = removeEmptyLeadingTrailing(desc) details['filename'] = filename dictionary[msgid] = details @@ -261,8 +339,6 @@ def processFileContent(filename, lines): addToDictionary(msgid, msgtext, description, filename) -# -# \param file Name of the file to process def processFile(filename): """Processes a file by reading it in and stripping out all comments and @@ -323,7 +399,7 @@ if __name__ == "__main__": # Read the files and load the data processAllFiles(args[0]) - # Now just list the message IDs and text in the global dictionary + # Now just print out everything we've read (in alphabetical order). count = 1 printHeader() for msgid in sorted(dictionary):