path: root/ReadMe.rst

QUIP module maintenance
=======================

This module contains
* The reStructuredText sources of all QUIPs (``quip-*.rst``)
* The scripts to process them (``quips.pro`` and ``scripts/``)
* A copy of Planet Qt as a sub-module

See ``html/``, once generated, for further details, or the preamble
for ``html/quip-000.html`` defined in ``scripts/gen-quip-0000.py`` for
a preview of what this is all about.

Generating HTML from QUIPs
--------------------------

You'll need this module checked out, along with its sub-module: see
`Planet Qt and the template`_ for how to get Planet Qt checked out and
up to date.

You can generate the HTML using ``qmake`` and ``make``, provided you
have (them and) both ``python`` and its ``docutils`` package
installed.
I recommend a shadow build: in some directory outside this source
tree, run ``qmake`` on ``quips.pro`` in this directory; then, in the
same directory, run ``make`` and it should generate a sub-directory
``html/`` containing the generated HTML and symlinks to the supporting
material from Planet Qt.
You can then point a web browser at the result and review it.

You can, of course, do the same in the source tree; you'll clutter it
with the generated content.
While ``.gitignore`` should save you from committing that, you can
clean up more robustly in an out-of-source build.

Checking
~~~~~~~~

It may be constructive to use checklink_ on the resulting HTML.
On Debian, this is available for local use from the package named
``w3c-linkcheker``; other systems probably have something similar.
It can be run (be patient; it takes several minutes) as::

 checklink -qbr html/quip-*.html

If that finds any broken links, check to see whether they derive from
the template (report to the planetqt maintainers) or from the source
of the QUIP (``quip-*.rst``, report to the relevant QUIP's author).
Some template links may use URLs without scheme,
e.g. ``href="//www.qt.io/terms-conditions/"``, which checklink shall
show as broken (since it's accessing links using ``file://``,
implicitly); these are not normally a problem.

.. _checklink: http://validator.w3.org/docs/checklink.html

Planet Qt and the template
--------------------------

When you update this module, you should ``git submodule update
--init`` to keep its ``planetqt/`` submodule in sync.
This shall normally be on a revision for which the scripts are known
to work.

Updating
~~~~~~~~

In the ``planetqt/`` submodule, you can ``git checkout master`` and
``git pull --ff-only`` to get an up-to-date version.
This might work fine with the existing scripts and templates, in which
case it's fine to ``git add planetqt`` in the super-module and commit.

However, if ``planetqt/template.qt`` has changed, it's possible the
scripts shall fail to generate ``template.html`` from it (in the build
directory, if different from the source directory).
The script first attempts this by applying ``scripts/template.diff``
to produce ``scripts/template.html``; if this had succeeded, the
result would have been moved to the build directory.
When it fails, a partially-patched ``scripts/template.html`` should
result in a ``scripts/template.rej`` file, containing the unapplied
hunks from the patch.
You'll need to manually adapt the patch's modifications to produce a
sensible ``template.html`` (see below) based on the new
``template.qt`` from Planet Qt.

Once you have a usable ``scripts/template.html``, run::

 $ diff -bu planetqt/template.qt scripts/template.html >scripts/template.diff

You might then want to move your working ``template.html`` to safety,
while you check that building works; your test build shall, otherwise,
stomp your ``template.html`` in the process of generating the one it
uses.
If it all works nicely, commit your updated ``template.html`` along
with the updated ``planetqt/``.

How the template works
~~~~~~~~~~~~~~~~~~~~~~

The template file, ``template.html``, is mostly used verbatim in the
generated web page for each QUIP, with a few tokens replaced, each of
which starts with a % character.
In particular, this means that any URLs in ``planetqt/template.qt``
that contain %-encoded tokens (as part of the usual URL-encoding) need
the % in each such token doubled up, to a %% that the reStructuredText
engine shall convert back to a single % in the generated web page.

The other tokens replaced are ``%(name)`` for various choices of
``name``; most of these are set up in ``scripts/quip2html.py`` by
``QuipWriter::interpolation_dict()`` adding entries to its ``subs``
mapping.
An entry for ``%(stylesheet)`` is generated from
``QuipWriter::settings_default_overrides['stylesheet_path']`` and
there may be more entries automagically added by the ``docutils``
infrastructure, 'though we don't presently exercise these.

Complications
~~~~~~~~~~~~~

When updating ``template.html`` from a new ``template.qt``, it is best
to change as little as possible: keep the ``diff`` small so that
``patch`` has a better chance of applying it.
Generally, that means only changing what you must, nothing more.
If you think the web-design of planetqt can be improved on, submit
changes to it, don't complicate your differences from it with changes
the next person updating this directory might not understand.

Under ``planetqt/website`` there are assorted files that shall be
referenced from your ``template.html``, expecting them to be in the
same directory.
There's also a sub-directory ``images/``.
All of these need to be visible in the generated ``html/`` directory;
this is arranged by a setup target in ``quips.pro`` which (to save a
lot of repetition) uses ``scripts/setup.mk`` to drive creation of
symlinks from ``html/`` to ``planetqt/website/``.
You'll need to keep the ``WEBFILES`` and ``WEBDIRS`` lists up to date;
each is a list of names, of files or directories respectively, within
``planetqt/website`` that are needed by the template.

If the new planetqt template contains a copyright notice, consult with
planetqt's owners about whether they're happy to have the adapted
template, without that notice, and accompanying linked content,
released under this module's CC0 license.
If they are, remove their license as part of adapting the template;
otherwise, work out some sensible way to satisfy their needs within
the framework of this module; you may need to find some other source
than planetqt for templates and styling.

Resist the temptation to replace the contents of planetqt/ with links
to files on planet.qt.io: doing so would make it necessary to keep
permanently in sync, instead of only updating when convenient.