#+TITLE: Stuff To Do

#+LATEX_COMPILER: xelatex

#+LATEX_CLASS: article

#+LATEX_CLASS_OPTIONS: [12pt]

#+LATEX_HEADER: \usepackage{xltxtra}

#+LATEX_HEADER: \usepackage[margin=1in]{geometry}

#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Latin Modern Roman}

* Project Task List

  :PROPERTIES:

  :CUSTOM_ID: task-list

  :END:

** DONE Documentation default format

   CLOSED: [2018-02-15 Thu 21:29]

   :PROPERTIES:

   :CUSTOM_ID: todo-docs-default

   :END:

   Decide on a default file format for documentation.  The two main

   contenders being Org Mode, the default for the GnuPG Project and

   reStructuredText, the default for Python projects.  A third option

   of DITA XML was considered due to a number of beneficial features

   it provides.

   The decision was made to use Org Mode in order to fully integrate

   with the rest of the GPGME and GnuPG documentation.  It is possible

   to produce reST versions via Pandoc and DITA XML can be reached

   through converting to either Markdown or XHTML first.

** TODO Documentation build systems

   :PROPERTIES:

   :CUSTOM_ID: todo-docs-build-systems

   :END:

Though Org Mode is being used for the default documentation format, it

still needs to end up as usable by end users.  So the Org Mode files

are used to produce the "source" files used by the two main contenders

for documenting the bindings: Texinfo and ReStructuredText/Docutils.

*** TODO Texinfo documentation

    :PROPERTIES:

    :CUSTOM_ID: todo-docs-build-texinfo

    :END:

Need to add all of Texinfo's ... special systems to make it do its

things.

*** TODO ReStructuredText documentation

    :PROPERTIES:

    :CUSTOM_ID: todo-docs-build-docutils

    :END:

Need to run Sphinx's quick start, add it to the requirements and tweak

the index page for the rst files to point to the HOWTO and other files.

It might just be easier to do all that in Org Mode and convert the

lot, then the Sphinx bits can be automated.

** STARTED Documentation HOWTO

   :PROPERTIES:

   :CUSTOM_ID: todo-docs-howto

   :END:

   - State "STARTED"    from "TODO"       [2018-03-08 Thu 13:59] \\

     Started yesterday.

   Write a HOWTO style guide for the current Python bindings.

*** DONE Start python bindings HOWTO

    CLOSED: [2018-03-07 Wed 18:14]

    :PROPERTIES:

    :CUSTOM_ID: howto-start

    :END:

*** STARTED Include certain specific instructions in the HOWTO

    :PROPERTIES:

    :CUSTOM_ID: howto-requests

    :END:

    Note: moved the S/MIME bits out to their own section of the TODO

    list and may be served better by separate HOWTO documentation

    anyway.

    - State "STARTED"    from "TODO"       [2018-03-09 Fri 15:27]

    Some functions can be worked out from the handful of examples

    available, but many more can't and I've already begun receiving

    requests for certain functions to be explained.

**** DONE Standard scenarios

     CLOSED: [2018-03-19 Mon 12:34]

     :PROPERTIES:

     :CUSTOM_ID: howto-the-basics

     :END:

     - State "DONE"       from "STARTED"    [2018-03-19 Mon 12:34] \\

       All four of those are done.

     - State "STARTED"    from "TODO"       [2018-03-09 Fri 15:26] \\

       Began with the example code, now to add the text.

     What everyone expects: encryption, decryption, signing and verifying.

**** STARTED Key control

     :PROPERTIES:

     :CUSTOM_ID: howto-key-control

     :END:

     - State "STARTED"    from "TODO"       [2018-03-19 Mon 12:35] \\

       Generating keys and subkeys are done, but revocation is still to be done.

     Generating keys, adding subkeys, revoking subkeys (and keeping

     the cert key), adding and revoking UIDs, signing/certifying keys.

**** DONE More key control

     CLOSED: [2018-03-19 Mon 12:36]

     :PROPERTIES:

     :CUSTOM_ID: howto-key-selection

     :END:

     - State "DONE"       from "TODO"       [2018-03-19 Mon 12:36] \\

       Key selection, searching, matching and counting is done.

     Selecting keys to encrypt to or manipulate in other ways (e.g. as

     with key control or the basics).

** TODO Documentation SWIG

   :PROPERTIES:

   :CUSTOM_ID: todo-docs-swig

   :END:

   Write documentation for the complete SWIG bindings demonstrating

   the correspondence with GPGME itself.

   Note: it is likely that this will be more in the nature of

   something to be used in conjunction with the existing GPGME

   documentation which makes it easier for Python developers to use.

** TODO GUI examples

   :PROPERTIES:

   :CUSTOM_ID: todo-gui-examples

   :END:

   Create some examples of using Python bindings in a GUI application

   to either match or be similar to the old GTK2 examples available

   with PyME.

** TODO Replace SWIG

   :PROPERTIES:

   :CUSTOM_ID: todo-replace-swig

   :END:

   Selecting SWIG for this project in 2002 was understandable and

   effectively the only viable option.  The options available now,

   however, are significantly improved and some of those would resolve

   a number of existing problems with using SWIG, particularly when

   running code on both POSIX compliant and Windows platforms.

   The long term goal is to replace SWIG by reimplementing the Python

   bindings using a more suitable means of interfacing with the GPGME

   C source code.

*** TODO Replacement for SWIG

    :PROPERTIES:

    :CUSTOM_ID: todo-replace-swig-replacement

    :END:

    Decide on a replacement for SWIG.  Currently CFFI is looking like

    the most viable candidate, but some additional testing and checks

    are yet to be completed.

** TODO API for an API

   :PROPERTIES:

   :CUSTOM_ID: todo-api-squared

   :END:

   A C API like GPGME is not what most modern developers think of when

   they hear the term API. Normally they think of something they can

   interact with like a RESTful web API.  Though RESTful is unlikely

   given the nature of GPGME and the process of encryption, it may be

   possible to provide a more familiar interface which can be utilised

   by developers of other languages for which bindings are not

   available or for which it is too difficult to create proper

   bindings.

** TODO S/MIME

   :PROPERTIES:

   :CUSTOM_ID: s-mime

   :END:

   Eventually add some of this, but the OpenPGP details are far more

   important at the moment.

* Project Task Details

  :PROPERTIES:

  :CUSTOM_ID: detailed-tasks

  :END:

** Working examples

   :PROPERTIES:

   :CUSTOM_ID: working-examples

   :END:

   The old GUI examples were unable to be retained since they depended

   on GTK2 and Python 2's integration with GTK2.

   Current GPGME examples so far only include command line tools or

   basic Python code for use with either Python 2.7 or Python 3.4 and

   above.

   Future GUI examples ought to utilise available GUI modules and

   libraries supported by Python 3.  This may include Qt frameworks,

   Tkinter, GTK3 or something else entirely.

** Documentation

   :PROPERTIES:

   :CUSTOM_ID: documentation

   :END:

   The legacy documentation which no longer applies to the Python

   bindings has been removed.

   Current and future documentation will adhere to the GnuPG standard

   of using Org Mode and not use the reStructuredText (reST) format

   more commonly associated with Python documentation.  The reasons

   for this are that this project is best served as shipping with the

   rest of GPGME and the documentation ought to match that.  There are

   also aspects of Org Mode's publishing features which are superior

   to the defaults of reST, including the capacity to generate fully

   validating strict XHTML output.

   If reST files are required at a later point for future inclusion

   with other Python packages, then that format can be generated from

   the .org files with Pandoc before being leveraged by either

   Docutils, Sphinx or something else.

   While there are some advanced typesetting features of reST which

   are not directly available to Org Mode, more often than not those

   features are best implemented with either HTML and CSS, with LaTeX

   to produce a PDF or via a number of XML solutions.  Both reST and

   Org Mode have multiple paths by which to achieve all of these.