======================
GenerateDS GUI Notes
======================

:author: Dave Kuhlman
:contact: dkuhlman (at) davekuhlman (dot) org
:address:
    http://www.davekuhlman.org

.. Do not modify the following version comments.
   They are used by updateversion.py.

.. version

:revision: 2.28b

.. version

:date: |date|

.. |date| date:: %B %d, %Y


:copyright: Copyright (c) 2016 Dave Kuhlman. This documentation
    and the software it describes is covered by The MIT License:
    http://www.opensource.org/licenses/mit-license.php.

:abstract: This document describes generateds_ui.py, the graphical
    front end to generateDS.py.

.. sectnum::    :depth: 4

.. contents::
    :depth: 4


Introduction
==============

``generateds_gui.py`` provides a graphical front end for
``generateDS.py``.  Some may find it easier to configure and to
select and set options for ``generateDS.py`` using this graphical
application.


Requirements
==============

You will need Gtk support for Python in order to run
``generateds_gui.py``.

You must run ``generateds_gui.py`` under Python 3.  Python 2 is not
supported.

Note that you can use the "--session" command line flag supported by
``generateDS.py`` on a machine that does not have Python Gtk support
installed.


Usage notes
=============

What it does
--------------

Here are some of the different ways that you can use
``generateds_gui.py``:

#. You can generate modules from within ``generateds_gui.py`` using
   the "Generate" item in the "Tools" menu.

#. You can produce and view a command line that reflects your
   configuration using the "Generate CL" item in the "Tools" menu,
   and then you can copy and paste the resulting command line into a
   ``bash`` script (for Linux) or a ``.bat`` file (for MS Windows),
   which you can then run from the command line.

#. You can run the session file that you've saved with the
   "--session" command line flag supported by ``generateDS.py``.

#. You can load a previously saved session file into
   ``generateds_gui.py`` using the "--session" command line option,
   and then modify that session and/or use it to generate modules,
   or to generate a command line.


How to use it
---------------

You can get some help by running the following::

    $ ./generateds_gui.py --help

Command line options and arguments::

	Usage:
        python generateds_gui.py [options] --session=<some_session_file.session>
	example:
		python generateds_gui.py --session=generator01.session
	Options:
	  -h, --help            show this help message and exit
	  --exec-path=EXEC_PATH
							path to executable generated in command line.
							Example: "python /path/to/generateDS.py".  Default:
							"./generateDS.py".  Use Tools/Generate CL (Ctrl-T) to
							see it.
	  --impl-gui=IMPL_GUI   name of glade file that defines the GUI if not
							embedded.
	  -s SESSION, --session=SESSION
							name of a session file to be loaded.

exec-path
    If your copy of ``generateDS.py`` is in a special location, you
    can specify that location using this option.  The version of
    ``generateDS.py`` at that location will be run when you select
    the "Generate" item from the "Tools" menu.

impl-gui
    The file ``generateds_gui.glade`` specifies and describes the
    user interface.  This file has been embedded into
    ``generateds_gui.py``.  If you modify ``generateds_gui.glade``
    and want to use that modified version, specify it with this
    option.

s, session
    If you have created and saved a session file using
    ``generateds_gui.py`` and want to load that file the next time
    you run ``generateds_gui.py``, use this option.  Alternatively,
    once ``generateds_gui.py`` has been started, you can use the
    "Load session" item under the "File" menu.


Internationalization
======================

*Note:* This work on internationalization for generateds_gui is
experimental and does not yet work.

Preparation
-------------

Here is what I've done::

    $ cd generateds/gui/
    $ mkdir po
    # Create the template file.
    $ xgettext -k_ -kN_ -o po/generateds_gui.pot generateds_gui.glade 
    # Create a file for the translator.  This one is for the Russian language.
    $ msginit --locale=ru --input=generateds_gui.pot 

And, after someone has added their translations (for example, to
``ru.po``), we translate it to binary with the following command::

    $ msgfmt -o generateds_gui.mo ru.po

Finally, move the binary file to the appropriate directory under the
directory containing the executable (``generateds_gui.py``).  See
`Installation and setup`_.


Installation and setup
------------------------

Now we have to move the ``.mo`` file where it will be used when we
run ``generateds_gui.py``.  We place it in a sub-directory under the
location of ``generateds_gui.py`` itself.

::

    $ cd /directory/containing/generateds_gui.py
    $ mkdir locale
    $ mkdir locale/ru
    $ mkdir locale/ru/LC_MESSAGES
    $ mv generateds_gui.mo locale/ru/LC_MESSAGES/


Additional information
------------------------

Here are some helpful references:

- https://en.wikipedia.org/wiki/Gettext
- http://faq.pygtk.org/index.py?req=show&file=faq22.002.htp
- http://www.servin.com/linux/GladeInternationalization.html
- http://www.learningpython.com/2006/12/03/translating-your-pythonpygtk-application/


.. vim:ft=rst:
