a982f91315
* Restructured the docs directory to account for the GNU preferred source doc format (.texi) and the Python preferred source doc format (.rst) and the real source doc format (.org). * Both the perceived source formats will need to be generated from the .org files and included at this stage. Unfortunately there is not yet a native org-to-rst transformation method in the org-mode software in Emacs nor is there a a direct means of going from reST to Org-mode from Docutils. There's only third party packages like Pandoc and, while very good, there is no guarantee of consistency; so we can't entirely automate this bit (yet).
220 lines
7.0 KiB
Org Mode
220 lines
7.0 KiB
Org Mode
#+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.
|
|
|
|
|
|
** 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.
|