/*!
    \contentspage{index.html}{QSource-Highlight}
    \page index.html

    \title QSource-Highlight

    QSource-Highlight is a Qt4 front-end for GNU Source-Highlight,
    \l{http://www.gnu.org/software/src-highlite}.

    \image qsource-highlight-art.png

    QSource-Highlight uses the library included in GNU Source-Highlight,
    since version 3, thus you need that library to build QSource-Highlight;
    in particular it uses Source-Highlight-Qt additional library,
    \l{http://srchiliteqt.sourceforge.net}, which provides highlighting
    in Qt relying on GNU Source-Highlight.  Thus, you need to install
    Source-Highlight-Qt as well.
    we refer to GNU Source-Highlight's and Source-Highlight-Qt's
    websites for further information about the library and its installation
    (you may want to check whether your distribution already provides
    packages for these two libraries).

    The home page of QSource-Highlight is \l{http://qsrchilite.sf.net}.

    QSource-Highlight is \bold{free and open source GPL} software.

    \list
       \o   \l{Download}
       \o   \l{Installation}
       \o   \l{Main Window}
       \o   \l{Settings}
    \endlist

    \section1 Download

    Sources and binaries (when available) can be downloaded from
    \l{http://sourceforge.net/projects/qsrchilite/files/}.

    You can also get the source code via \bold{git} (this way you will also access
    the latest version - probably the one in development stage, and not yet
    released):

    \code
    git clone git://qsrchilite.git.sourceforge.net/gitroot/qsrchilite/qsrchilite
    \endcode
    
    and you can also browse the repository at
    \l{http://qsrchilite.git.sourceforge.net}.

    \section1 Installation

    We suggest to create a \c{build} directory, cd to that directory and
    then run qmake accordingly

    \code
    qmake -recursive ../qsource-highlight.pro
    \endcode

    and then run \c{make}; the binary will be created in the \c{bin} directory.

    Once the building has sucessfully finished, you can install the files with
    the command \c{make install}; binaries will be installed into \c{/bin}
    and documentation (the one readable with qt assistant)
    into \c{/share/doc/qsource-highlight} and html documentation
    into \c{/share/doc/qsource-highlight/html}.
    You can customize the root of
    the installation directory with the environment variable \c{INSTALL_ROOT};
    for instance,

    \code
    INSTALL_ROOT=$HOME/usr/local make install
    \endcode

    You might need to become root if you install in a path different
    from your home.

    The qmake project of QSource-Highlight uses \bold{pkg-config},
    \l{http://pkg-config.freedesktop.org} to
    detect the library Source-Highlight-Qt (and implicitly also the
    GNU Source-Highlight library).  If the library is installed in a standard
    system path (e.g., \c{/usr}) running \c{qmake} should be enough; otherwise
    you should tell \c{pkg-config}, through the environment variable
    \bold{PKG_CONFIG_PATH}, where to find the .pc file of
    source-highlight-qt4 (\c{source-highlight-qt4.pc}; note that this file
    will also contain the references to GNU Source-highlight library and
    headers, so you won't have to worry about that).  For instance, if you've
    installed source-highlight-qt4 using the prefix \c{~/usr/local}, the
    .pc file will be installed into \c{~/usr/local/lib/pkgconfig}, thus
    you should run qmake as follows:

    \code
    PKG_CONFIG_PATH=~/usr/local/lib/pkgconfig qmake -recursive ../qsource-highlight.pro
    \endcode

    If pkg-config is not installed in your system, you'll have to specify
    the \c{LIBS} and \c{INCLUDEPATH} qmake variables manually (e.g.,
    by modifying the .pro file), using the correct path, for instance:

    \code
    LIBS += -L~/usr/local/lib -lsource-highlight-qt4
    INCLUDEPATH = ~/usr/local/include
    \endcode

    \section1 Main Window

    The main window of qsource-highlight permits opening a file to highlight,
    to tweak some highlighting options, and to see the output of highlighting:

    \image qsource-highlight-main-window.png

    A preview of the highlighted output is available for some output formats
    (e.g., HTML, XHTML, etc.).

    The language definition file is automatically selected according to
    the input file extension, but you can change it manually by using the
    corresponding combo box.  In particular you have three combo boxes:

    \list
        \o the combo box for the input language definition (e.g., C, C++,
        Java, etc.); in particular, the combo box refers to the \c{.lang}
        files of Source-Highlight, which, however, should have quite
        intuitive names.
        \o the combo box for the output format (e.g., HTML, LaTeX, etc.);
        in particular, the combo box refers to the \c{.outlang}
        files of Source-Highlight, which, however, should have quite
        intuitive names (e.g., \c{htmltable.outlang} generates HTML
        output into an html table).
        \o the combo box for the highlighting style (e.g., colors, and
        formats of the elements of the language); these elements refer to
        Source-Highlight \c{.style} files and to \c{.css} files.
    \endlist

    All the files named in these combo boxes refer to files shipped with
    Source-highlight, and they are searched for in the Source-highlight
    corresponding installation path.  In case the combo boxes are empty,
    then the path where source-highlight searches for these files is
    wrong: you should then configure the correct path for source-highlight
    using the settings dialog (\l{Source-Highlight Settings}).

    The icons corresponding to actions available in QSource-Highlight should
    be quite standard and their meaning should be immediate; however, there
    are some that require some explainations:

    \table
        \row
            \i  \inlineimage icons/fileopen.png
            \i  This opens a file as an input file (whose contents can
            be edited, but, most of all, highlighted).
        \row
            \i  \inlineimage icons/fileopenstyle.png
            \i  This opens a style file to be used for highlighting.
            Note that this is useful when you have your own style file
            that is not part of source-highlight style files (thus it would
            not be selected in the corresponding combo box).
        \row
            \i  \inlineimage icons/filesave.png
            \i  Saves the current input file.
        \row
            \i  \inlineimage icons/filesavehighlighted.png
            \i  Saves the current output file (i.e., the output of highlighting).
        \row
            \i  \inlineimage icons/filesavestyle.png
            \i  Saves the current style file (see also \l{Style Settings}).
        \row
            \i  \inlineimage icons/highlight.png
            \i  Highlights the current input file using the selected language
            definition file, the selected output format and the selected
            style.
        \row
            \i  \inlineimage icons/highlightselected.png
            \i  As above, but highlight only the currently selected lines of
            the input file.
    \endtable

    \section2 Options

    On the main window there is also an "Options" pane which can be used to
    tweak source-highlight formatting options.  We refer to the documentation of
    source-highlight for further details; here we only briefly summarize the
    main options:

    \section3 Document options

    \list
    \o \bold{entire document}: generates a complete document with the highlighted
    output; the semantics of "entire" strictly depends on the formatting output
    (e.g., for HTML it means that html header will be used, for LaTeX that an output
    that can be compiled in isolation will be produced, etc.).
    \o \bold{header & footer}: you can specify header and footer files that will
    be used in the formatted output (required the "entire document" option).
    \o \bold{tabs to spaces}: tabular characters in the input are converted in
    the output into the corresponding number of spaces.
    \endlist

    \section3 Line options

    \list
    \o \bold{Line numbers}: generates line numbers in the highlighted output
    (you may want to try the sub options and see what happens to the line
    numbers).
    \o \bold{Context lines}: if only selected lines are highlighted, this option
    permits to specify the number of "surrounding context" lines to be put in the
    output as well (without highlighting though).
    \endlist

    \section1 Settings

    \section2 Style Settings

    You can use the highlighting style dialog to customize the current
    highlighting style:

    \image settings-style.png

    This provides a way to customize the output style of each language
    element recognized by the current language definition file
    (e.g., keywords, comments, symbols, etc.).  You can also save the
    currently customized style.

    \section2 Source-Highlight Settings

    Source-highlight library uses a path (called data dir) to search for
    language definition file, output format definition files, style files,
    etc.  This path must be set correctly otherwise highlighting features
    will not work.  In a standard installation this path should already be
    set appropriately.  However, if you use a non standard installation of
    source-highlight, this path might not be set correctly (a symptom,
    as said in the previous section, is when the combo boxes are simply empty).
    You can set this path using the \c{Settings -> Source-highlight Settings}
    menu.  This will bring a dialog where you can set the path (or choose
    it with the browse button); notice that the dialog also checks whether
    the currently selected path is a valid path for source-highlight.

    \section3 Tip:
    In order to be a valid path, it should contain at least
    \c{lang.map} file and \c{.lang}, \c{.outlang}, \c{.style} files.

    \image settings-wrong.png

    \image settings-ok.png

*/

