man: Fix minor errors

- The set of accepted values for WAFFLE_CONTEXT_PROFILE depends on more
  than just WAFFLE_CONTEXT_API, as clearly stated in the clause above the
  correction.

- Move missplaced 'or'.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
core: Rewrite wcore_config_attrs_parse()

Rewrite in order to interleave assignment of default values and the
parsing of the attrib list for different attribute groups. No behavioral
change is expected.

Before, wcore_config_attrs_parse() did these steps:
    - set default misc attributes
    - parse api
    - set default context version
    - parse and validate all attributes but api

Now wcore_config_attrs_parse() does these steps:
    - validate all key names
    - parse api
    - set default context version then parse context version
    - set default profile then parse profile
    - set default misc attributes and parse

The prompt for this patch is that the next commit alters the behavior of
the profile attribute in a way that requires the interleaving.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
waffle: Change WAFFLE_CONTEXT_PROFILE behavior for GL

This patch changes the behavior of WAFFLE_CONTEXT_PROFILE when the
requested api is WAFFLE_CONTEXT_OPENGL.

At commit a40dec1~1 (Nov 12), the behavior was:
    - For GL < 3.2, require that the profile be WAFFLE_NONE, core,
      or compat.
    - For GL >= 3.2, require that the profile be core or compat.
This is the behavior released in waffle-1.1.

However, the waffle_config manpage documented requirements for
WAFFLE_CONTEXT_PROFILE that differed from the implementation. The
documented requirements imitated the EGL_KHR_create_context and
GLX_ARB_create_context_profile specs.  Commit a40dec1 (Nov 12) changed the
behavior to match the manpage:
    - For GL < 3.2, completely ignore the profile value.
    - For GL >= 3.2, require that the profile be core or compat.
This behavior had looser requirements than a40dec1~1 because the profile's
value was not validated for GL < 3.2. No waffle release contains a40dec1.

The GLX working group, though, can't decide on the exact behavior of
profile bit.  A later GLX extension, GLX_EXT_create_context_es_profile, is
built on top of but breaks backwards compatibility with
GLX_ARB_create_context_profile. According to
GLX_EXT_create_context_es_profile, the profile *is* signficant for all
versions of GL when its value is GLX_CONTEXT_PROFILE_ES_BIT_EXT.

Rather than attempt to predict what the GLX working group will decide
next regarding the profile bit, Waffle should be as restrictive as
possible in its interpretation of WAFFLE_CONTEXT_PROFILE. Being
restrictive decreases the possibility that Waffle will accept something
that a later GLX extension will reject, a situation that would likely
result in modifying the public interface or internal ugliness.

This patch changes the behavior to be more sightly more restrictive than
a40dec1~1:
    - For GL < 3.2, require that the profile be WAFFLE_NONE.
    - For GL >= 3.2, require that the profile be core or compat.
It will be straightforward to later loosen these requirements if necessary
in response to a new GLX or EGL extension.

This patch also updates the waffle_config manpage and wcore_config_attrs
unittests accordingly.

Even though the current requirements are more restrictive than those
released in waffle-1.1,  I don't expect this to change to break any
clients. The only clients I'm aware of are Piglit, which is not affected
by this change, and some experimental unreleased apps.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
readme: List required pkgs for Archlinux

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
readme: List required packages for each platform

To build support for each platform, list the required packages for
Archlinux and Fedora.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
readme: For build requirements, state Fedora version

State that Fedora package requirements are for Fedora 17.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
readme: Clarify instructions for PKG_CONFIG_PATH

Reported-by: Brian Johnson <bjthinks@gmail.com>
Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
readme: Mention -Dwaffle_has_gbm=1

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
readme: Organize installation instructions into sections

I've seen several people stumble through the installation instructions.
I can only assume that the instructions were not sufficiently clear.
Organizing into sections should help.

This doesn't substantially change the context, it just reorders it.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
readme: List where to find example code

Brian complained that the README didn't tell him how to find example code.
Add a new section "Examples" to fix the problem.

Reported-by: Brian Johnson <bjthinks@gmail.com>
Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
readme: Fix minor typo

s/want to use the invoke cmake/want to call cmake/

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
man: Move manpage rules into new file, manpages.cmake

The next commit adds cmake rules to build html documentation. To keep
things easier to separate, this patch splits out the rules to build the
manpages into a new file.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
man/cmake: Factor out list of common source files

That is, factor out sources that will be common to manpages.cmake and
the soon-to-arrive htmldocs.cmake into man/CMakeLists.txt.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
man: Factor out shared xsl

That is, move xsl that will be shared between manpage.xsl and the
soon-to-arrive html.xsl into a new file, common.xsl.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
man: Split waffle_gl_misc(3)

Having a "gl_misc" manpage was silly. Let's simply document each function
separately.

Remove the waffle_gl_misc manpage and split it into a separate manpage for
each function: waffle_get_proc_address, waffle_is_extension_in_string, and
waffle_make_current.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
man/waffle_dl: Add reference to waffle_get_proc_address

The two functions are closely related.  Add waffle_get_proc_address to the
SEE ALSO section.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
man,cmake: Generate html documentation

Add new cmake option `waffle_build_htmldocs`. Default is off.

Add some new cmake rules and an html.xsl to generate the docs. The output
directory is /doc/html. Install the html docs to
CMAKE_INSTALL_DOCDIR/html.

All citations, even those to GLX and EGL functions, have correct urls.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
man: Use citations for GLX and EGL functions

Change every reference to a GLx and ELG function into a <citerefentry>.
This ensures that links are created in the htmldocs.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
readme,doc: Document how to build html docs

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>
gitignore: Make rules more specific, use abspaths

I don't like it when git ignores something that it shouldn't.

Some rules were too broad. This patch replaces broad rules
with specific ones and uses absolute paths when possible. For example,
replace
    *test -> /tests/unittests/waffle-unittest
          -> /tests/functional/gl_basic_test

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>