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.