= Introduction

    This is whata-php, a parser for the [whata] Syntax.

    - ``whatadom.php`` is the part which translates a [whata] document to a tree representation.
        Here is an example of usage from a PHP script :
        [code=php <<<
            // Your document:
            whataDoc = '...';

            // you can override the default configuration by setting the
            // $whata_override_conf array so every call of whata will use
            // the supplied configuration by default:

            $whata_override_conf = array(
                'MATH_METHOD'   => 'function',
                'MATH_FUNCTION' => 'whata_MathJax',
                'GESHI_URL'     => 'geshi/geshi.php'
            );
            // obviously, this is not mandatory.

            include('whata-php/whatadom.php');

            $conf = array(
                'lang'   => 'en',
                'xhtml'  => true,
                'html5'  => true,
                'imgdir' => '/images/'
            );
            // Passing the $conf array is optional.
            // see later for the explanations on the $conf array.

            $dom = whataDOM($whataDoc, $conf);

            print_r($dom); // this outputs a huge amount of data
        >>>]

    - ``whata2html.php`` is the part which translates the tree representation of a document to HTML. It also has a convenient function which translates a [whata] document directly to HTML, which most people will want to do.

        - Usage 1 : Replace the last line of the last snippet of code by : [code=php <<< echo whatadom2html($dom, $conf); >>>]
        - Usage 2 (more direct) :

            [code=php <<<
                // Your document:
                whataDoc = '...';

                // ... the same as the last snippet ...

                include('whata-php/whata2html.php');

                $conf = array(
                    'lang'   => 'en',
                    'xhtml'  => true,
                    'html5'  => true,
                    'imgdir' => '/images/',
                    'processFootnotes' => true
                );
                // Passing the $conf array is optional.
                // see later for the explanations on the $conf array.

                echo whata2html($whataDoc, $conf);
            >>>]
        - Usage 3 (footnotes treated separately, getting further informations on the document, handling mathematics) :

            [code=php <<<
                // Your document:
                whataDoc = '...';

                // ... the same as the last snippet ...

                include('whata-php/whata2html.php');

                $conf = array(
                    'lang'   => 'en',
                    'xhtml'  => true,
                    'html5'  => true,
                    'imgdir' => '/images/',
                    'processFootnotes' => false // footnotes are separated
                                                // from the document
                );

                // Passing the $conf array is optional.
                // see later for the explanations on the $conf array.

                $html = whata2html($whataDoc, $conf);

                if ($conf['needMaths']) {
                    // Mathematics were used in the document. If you are using
                    // the MathJax method for displaying maths, you should
                    // include MathJax in your HTML document:

                    $https = true;

                    $mathJaxPath = $https ?
                        ? 'https://cdn.mathjax.org/mathjax/latest'
                        : 'http://cdn.mathjax.org/mathjax/latest';

                    echo '<script type="text/javascript" src="'
                                   . $mathJaxPath .
                         '/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
                        <script>
                            MathJax.Hub.Config({
                                tex2jax: {
                                inlineMath : [],
                                displayMath : [],
                                ignoreClass: "tex2jax_ignore",
                                processClass: "tex2jax_process",
                            //  preview: "none",
                                preferredFont: "STIX",
                                processEnvironments: false
                                }
                            });
                        </script>';
                }

                /* you can get the title, the author or the date of the document is you want to. */
                if (isset($conf['sets']['title'])) {
                    echo '<p>Title of the document : ', whatadom2html($conf['sets']['title'], WHATAHTML_INLINE, $conf), '</p>';
                }

                if (isset($conf['sets']['author'])) {
                    echo '<p>Author of the document : ', whatadom2html($conf['sets']['author'], WHATAHTML_INLINE, $conf), '</p>';
                }

                if (isset($conf['sets']['date'])) {
                    echo '<p>Date of the document : ', whatadom2html($conf['sets']['date'], WHATAHTML_INLINE, $conf), '</p>';
                }

                echo $html;

                // process footnotes separately here
                $footnotes = whatahtml_process_footnotes($conf);
                echo $footnotes;
            >>>]

            Any value present in the [set ] tag for the document can be retrieved like in the last snippet.

            If you need a block instead of inline HTML behavior, you can use ``0`` instead of ``WHATAHTML_INLINE``.

            if you need a raw string rather than an HTML string, you can use the ``whata_text_content()`` function of ``whatadom.php``:

            [code=php <<<
                echo '<p> Date of the document, as text: ', htmlspecialchars(whata_text_content($conf['sets']['date'])), '</p>';
            >>>]

    - ``htmlwhata-tools.php`` is a chunk of code which in theory helps in generating good documents from templates and which is configurable. See ``htmlwhata`` for an example of usage.
    - ``htmlwhata`` is a program (PHP script in command line) for translating [whata] document into complete HTML documents and supports templates / config options.
= The ``$conf`` array.

    ``$conf`` is an associative array which can optionaly be passed to ``whatadom``, ``whatadom2html`` and ``whata2html``.

    The following values are recognized by ``whatadom``:

    - ``basedir``: the path to files or documents referenced by relative links in [whata] documents
    - ``imgdir``:  the path to the images directory. Defaults to ``basedir``
    - ``xhtml``:   if true, will generate a XHTML-valid document. Default to ``false``.
    - ``html5``:   if true, will use HTML5 tags. Defaults to ``true``.
    - ``linkToWhataPrefix``: string to prepend to document names referenced in links like ``doc:your-document`` or ``part=your-document``. Defaults to the empty string.
    - ``linkToWhataSuffix``: string to append to document names referenced in links like ``doc:your-document`` or ``part=your-document``. Defaults to ``.xhtml`` if xhtml is true, ``.html`` otherwise.
    - ``docRefCallback``: callback function which will be called each time another [whata] document is referenced in the document. Passed parameters are :
        - the path to the [whata] file
        - the URL which is used in the generated document to access the referenced document (using ``linkToWhataPrefix`` and ``linkToWhataSuffix``).
    - ``lang``: the language in which the document is written.

    ``whata2html`` calls ``whataDOM`` so it understands all the previous options. It also calls ``whatadom2html`` which understands the additional following options: (to be writen)

= PHP 8 Support

Whata works on PHP8, but GeSHi is untested and may not work on this version.