Remove broken clean_hostname trace messages

The trace messages in krb5int_clean_hostname were outputting the
entire contents of the output buffer (mostly uninitialized garbage)
into the trace log.  Since these messages were essentially redundant
with messages in the callers, and were arguably at too low of a level
to begin with, simply remove them.

ticket: 7459 (new)
target_version: 1.11
tags: pullup
Update feature list in the documentation

In Quick facts section:
 - restructure the Supported platforms section;
 - do not tie KfW to 1.11 release;
 - move references to GSS-API extensions to Feature list table.
In Feature list section:
 - reformat the table;
 - move PRNG and Pre-auth mechanisms into their own tables;
 - clarify GS2 feature description;
 - reference rfc6680 for GSS-API naming extensions.
Lowercase the words in the title of the document.

ticket: 7455
Document krb5_get_init_creds_opt_set_in_ccache

More specifically, document that this new API was first
introduced in 1.11

ticket: 7460
Remove .doctrees when cleaning src/doc

Sphinx produces .doctree pickles that can be over 17MB with the
current documentation.  Remove them when running "make clean" in
src/doc so that they don't pollute distribution tar files.

ticket: 7461 (new)
target_version: 1.11
tags: pullup
Move Release tag into footer for Sphinx HTML

The current position of the Release tag is in the body of the main page
of the Sphinx html.  Move it to the footer.  This way the release number
can be viewed from every page.

ticket: 7462
Remove Test Coverage topic from documentation

ticket: 7464
Use en dash instead of hyphen

It should not be bracketed in whitespace.

ticket: 7447
tags: pullup
target_version: 1.11
Make krb5_trace_info a typedef

Our doxygen-to-sphinx documentation bridge only processes typedefs
and not structure definitions, since we almost universally use
typedefs for our data structures.  krb5_trace_info is the sole
exception, so bring it into the fold.

While here, flesh out the comment a bit more.

ticket: 7447
tags: pullup
target_version: 1.11
Update doxygen markup in krb5.hin

A few places were using the standard C /* comment */ form, but
this is rendered poorly by doxygen through to our Sphinx bridge.
Use the special /**< comment */ form to get doxygen-specific behavior.
If the standard C comment form is used, the full comment (including
start and end markers) is included in the value of the macro, and
Sphinx then tries to treat the end of the comment as the start of
inline markup with no corresponding end-string, which is a warning.
Using the doxygen form of the comment, the contents of the comment
are put in a separate paragraph block, which is inserted in the
body of the generated RST document.

The markup for krb5_rd_priv() had a line that ended with an @c
markup statement without a symbol following it.  This confused
doxygen into not parsing any more of the comment.  The beginning
of the next line is a macro identifier with markup to auto-linkify it.
In RST, it is not possible to have a link and a terminal font on the
same text, so removing the @c is the appropriate fix.

There are also eleven deprecated functions which are replaced by
the krb5_c_* family of functions.  However, referring to this class
of functions as the "krb5_c_" class of functions results in Sphinx
attempting to interpret this statement as a link to a label elsewhere
in the document, and no such label exists.  To avoid this warning, use
"krb5_c_*" to refer to the class of functions, which is arguably
more correct anyways.

ticket: 7447
tags: pullup
target_version: 1.11
Fix overflowing cell in HTML table

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
Exclude lists for doxygen API docs

Doxygen will pick up every function, macro, and typedef defined
in krb5.h; some of these may not actually be part of the public
API for one reason or another.  Provide hardcoded exclude lists
for macro/function/type names for which we do not want to emit
reStructuredText documentation, and check these lists when processing
the Doxygen XML output.

Seed these lists with the macros TRUE, FALSE, KRB5_OLD_CRYPTO,
KRB5_GENERAL__, KRB5_CALLCONV, KRB5_CALLCONV_C, KRB5_CALLCONV_WRONG,
KRB5INT_BEGIN_DECLS, KRB5INT_END_DECLS, and KRB5_ATTR_DEPRECATED,
and typedefs krb5_cc_ops and krb5_responder_context. The booleans
are compatibility cruft that we do not want to advertise, and the other
macros are for internal use for signalling and platform compatibility.
The typedefs are functioning just as forward declarations.

For consistency, remove KRB5_OLD_CRYPTO.rst from the macros index; it had no
content even when we did generate it.

ticket: 7447
tags: pullup
target_version: 1.11
Handle multiline macro definitions

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

ticket: 7447
tags: pullup
target_version: 1.11
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.)

This will cause a warning for macros that only cause a
symbol to be defined, that is, a literal "#define MACRO" with no
initializer, due to the lack of body in the inline-literal markup.
Such macros should probably be added to the exclude list for conversion
to reStructuredText in the Doxygen--Sphinx bridge, as was already
done for KRB5_OLD_CRYPTO.  Support code to programmatically omit
macros of this sort is deliberately *not* included, so that explicit
action must be taken when a new macro is to be undocumented.

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

ticket: 7447
tags: pullup
target_version: 1.11
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.

ticket: 7447
tags: pullup
target_version: 1.11
Do not generate unused parts of toctree

Our css only displays up to depth 3 of the toctree, partially
because the API reference content explodes at depth 4 and that would
not be pretty to see in the sidebar.  However, we would previously
always generate HTML for the full toctree and hide parts with CSS.
For the apiref, this proved to be about 65k per html file, and we
have one html file per function/type/macro.

Limit the depth of the toctree that gets generated to save on space
in the release tarball.

Unfortunately, there seems to be a Sphinx bug wherein the toctree
will only be generated to depth 1 for a document at a depth greater
than the maxdepth of the toctree, so the sidebar table of contents
on individual apiref pages will just be the toplevel toctree.
This issue is being tracked at
https://bitbucket.org/birkenfeld/sphinx/issue/1046/

ticket: new
tags: pullup
target_version: 1.11