/*
 * Project: MoleCuilder
 * Description: creates and alters molecular systems
 * Copyright (C)  2014 Frederik Heber. All rights reserved.
 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
 */

/**
 * \file userguide.dox
 *
 * Created on: Apr 18, 2014
 *    Author: heber
 */

/**
 * \page userguide How to write the userguide
 *
 * The userguide is written with docbook. We have use XXE as means to write
 * the guide in a WYSIWYG style.
 *
 * In general, the guide 
 * http://movementarian.org/docs/docbook-autotools/index.html
 * has been very helpful in setting docbook usage up with autotools. We
 * followed it closely with some minor modifications as we want to generate
 * a pdf instead of html.
 *
 * \section userguide-images How to get images working
 *
 * We have multiple screenshots to explain the graphical interface. These
 * reside in a distinct folder pictures. However, to get it working with
 * autotools we need to change some paths. And there we ran into a lot of
 * (newbie) trouble with docbook or rather with xsltproc, the preprocessor
 * for xml files in conjunction with xsl stylesheets. 
 *
 * At one point we stumbled over catalogs that seem to be able to tell the
 * processor that he should look elsewhere for certain files but we could
 * get the processor to actually use these directives.
 *
 * Finally, we stumbled on some more and came onto this guide
 * http://www.sagehill.net/docbookxsl/GraphicsLocations.html
 * that finally explained what was the point with those images. So, we can
 * use either \a fileref, which might work if we set \a img.src.path, or we
 * have to define our images as entities in the very beginning of the xml
 * document and reference them via \a entityref with just the given token.
 * The latter then worked with the catalog as these are actually looked up,
 * i.e. here the URI mechanism does finally work. It does not work in the
 * case of fileref.
 *
 *
 * \date 2014-04-18
 *
 */