Fix quoting issues in LDAP KDB module

Modify ldap_filter_correct() to quote special characters for DN
strings as well as filters, since it is already used to quote a DN
string in krb5_ldap_name_to_policydn() and there's no harm in
over-quoting.  In krb5_ldap_put_principal(), quote the unparsed
principal name for use in DNs we choose.  In
krb5_ldap_create_password_policy(), use the policy name for the CN of
the policy entry instead of the (possibly quoted) first element of the
DN.

Adapted from a patch by Jim Shi <hanmao_shi@apple.com>.

ticket: 7296
Add "Kerberos" to PDF titles

ticket: 7451 (new)
tags: pullup
target_version: 1.11
Reword krb5_unparse_name_ext doxygen markup

Avoid using asterix characters in the documentation for
krb5_unparse_ext_name, since they get intepreted as markdown
punctuation when translated to RST.

ticket: 7452 (new)
target_version: 1.11
tags: pullup
Fix heimdal/MIT differences table PDF rendering

sphinx-build defaults to the 'tabulary' environment for tables,
but uses regular 'tabular' for those involving literal blocks,
since tabulary does not handle them properly.  It seems that this
deficiency of tabulary also applies to inline literals, which
are rendered as \code{} sections by the latex builder.
Fortunately, sphinx provides a workaround to force a particular
column specification for the table.

The requirement for a table:: statement after the tabularcolumns::
statement is very poorly documented.

ticket: 7447
tags: pullup
target_version: 1.11
Handle adjacent notes from doxygen more correctly

The Doxygen documentation seems to claim that adjacent @note entries
will be collapsed into a single "note" element, as separate paragraphs.
This seems to be reflected in the XML output, multiple <para> entries
in a single <simplesec kind="note"> with a <simplesecsep/> element
between them.
Our XML-to-RST converter gets the entire contents of the simplesec
element, parsed into a unicode string with a single newline between
paragraphs.  Paragraphs seem to always start with two spaces, though
I have not tracked down the origin of this behavior.  Prior to this
commit, we would just output this entire unicode string directly.
Since our template puts a tab character before the note string, this
means that the first paragraph is indented by a tab and two spaces,
and the second paragraph by just two spaces.  Sphinx warns about this,
as "block did not end with blank line; unexpected whitespace", and
the paragraphs are indented differently within the note.
Fix the warning by checking for newlines in the interior of the
parsed unicode string, and introducing the appropriate whitespace
for the Sphinx parser.

ticket: 7447
tags: pullup
target_version: 1.11
Fix unknown target name warnings from Sphinx

Several (deprecated) functions have doxygen comments in krb5.hin
noting that they are replaced by the krb5_c_ family of functions;
the trailing underscore causes Sphinx to think that these are
markup, when really it just refers to the krb5_c_* family of functions.
Make the one-character change in the eleven places affected to
quiet the warnings.

ticket: 7447
tags: pullup
target_version: 1.11
Reformat comment for doxygen

If we have a standard C-style comment /* comment */ then Sphinx will
think that the end of the comment is the start of inline markup
and warn that there is no corresponding end-string.  Use the special
form of the start of the comment so that doxygen does not try to keep
the comment as part of the value of the macro definition.
In the XML representation, this puts the comment in a separate
paragraph block, which is put in the body of the RST document for
usage by Sphinx.
More doxygen comment fixes
Render macros as literals

Some convenience macros are referring to and dereferencing pointers,
and Sphinx will get a bit confused trying to inerpret this as markup.
There should never be any markup intended to be interpreted in the
value of a macro definition, so we can silence this class of
warnings by treating them as literals.  (In some sense, they actually
are literals, too.)

While here, do not generate documents for macros that only cause a
symbol to be defined, that is, a literal "#define MACRO" with no
initializer.  The generated documentation is not useful in these
cases, and attempting to use the markup for a literal string with
an empty string produces unfortunate results.

Also, strip leading and trailing whitespace from the macro name,
since this also causes problems with the markup.
Remove outdated include

We no longer generate KRB5_OLD_CRYPTO.rst since the macro does not
have an initializer.  Don't try to include it in the table of contents.
Handle multiline macro definitions

Compress them onto one line for printing in the generated table.
Remove outdated include

krb5_trace_info is a struct without a typedef, so we have never
generated a RST file for it.
Remove it from the table of contents accordingly.
Add some files previously missed

Sphinx warns that these documents weren't included in any toctree.
Include them.
(TRUE and FALSE are perhaps a bit questionable...)
Fix Sphinx warning
Definition list ended without blank line, since there was no
definition for the last item in the list (Windows).
Put in the flavors of windows as the bullet item to add a definition
and resolve the warning.
Tweak markup

Having @c at the end of the line causes doxygen to get confused
and stop reading the entry(?); when going to RST output, using
@c with automatic link generation (#symbol) does not actually render
in a typewriter font anyway.
Remove last "document not in toctree" warnings

There were two of them, for notice.rst and mitK5license.rst.
The former is included in the latter, which is linked to from
the mitK5features document but not listed in a table of contents
otherwise.  Includes are processed unconditionally, so we can
add notice.rst to the exclude_patterns array (formerly unused_docs)
and its content will still be included.

If we attempt to do the same for mitK5license.rst, it is not processed
at all, and the attempt to link to it will fail.  Instead, put a dummy
table of contents in the mitK5features document (which links to the
license document), with the "hidden" attribute.  This satisfies the
Sphinx need to know where all the input documents are without changing
the displayed table of contents.