EasyGnuPG

[Ben McGinnes]

On Tue, Mar 22, 2016 at 10:21:31PM +0100, Peter Lebbing wrote:
> On 22/03/16 20:53, Dashamir Hoxha wrote:
> 
> > the docs are like a maze and not clearly structured
> 
> A reasonably fair criticism... writing good documentation is hard,
> very hard. In fact, it turned out to be easier to write academical
> papers on why it is so difficult to make crypto easy to use than to
> write documentation that makes crypto easy to use.

Which is something I want to get right from the outset with GPyGME,
even knowing that it's going to make the job much bigger in the
process.  With the PyME bindings, for instance, the documentation
consists of "read the GPGME documentation" and that documentation
basically consists of "this documentation is generated at compile time
from in-line code snippet comments."

Then people wonder why GPGME isn't used more often ... that right
there is precisely why it isn't used more often.

And that doesn't even get into the issues involved with selecting a
format for producing the documentation in.  Consider the following:

1. As a Python 3 project there is an expectation that source
   documentation SHOULD be in reStructuredText, as with all other
   Python documentation (including python.org docs).  This facilitates
   generating end user documentation in [X]HTML 4 at build/install
   time with Sphinx.

2. As a GNU Project official project there is an expectation that
   source documentation SHOULD be in Org-Mode text, as with all other
   core GNU Project projects.  This facilitates generating end user
   documentation in texi (for man and info pages) and (optionally)
   [X]HTML 4 at build/install time.

3. Most contributors not familiar with either standard Python practice
   or stnadard GNU Project practice will prefer to fallback to
   Markdown, particularly the GitHub variant.

4. Pandoc based conversions between reStructuredText, Org-Mode and
   Markdown are not always entirely consistent.  This is because all
   Pandoc conversions convert to the Pandoc specialisation of Markdown
   first and then convert to other formats.

5. Best practices for technical documentation, especially with
   multiple contributors favours mark *up*, such as an XML dialect as
   it is easier to guarantee consistent source and to produce
   consistent output.  Whereas managing multiple text-based source
   documents becomes more and more unwieldy with each additional
   contributor's chosen/preferred format and implementation.

6. Current best choice for technical documentation of anything with
   many components and/or subcomponents (which both GPGME and GPyGME
   definitely qualify as) is to use a topic based XML format.  The
   lead candidate for this being the DITA implementation of XML,
   particularly since it allows for project specific specialisation
   *without* breaking the DITA standard (unlike DocBook).  See also:
   http://dita.xml.org/

Obviously there's a few contradictions there ... ain't it fun!  ;)

I favour DITA (usually with the DITA for Publishers specialisation),
but I also realise that most contributors will be coders first and not
writers first, so I may just have to accept that XML can't be used at
all.  In which case chances are I'll need to send everything through
Pandoc to produce both .rst and .org output and call both of them the
source files.  On the other hand, there's still time to try a few
things and make a final decision, though it will probably require both
.rst and .org files existing prior to build time just to conform with
existing systems like the GNU build toolset and the Python setuptools
and docutils libraries.

As for my preference for DITA and what it can do, I have been
experimenting with Don Day's rest2dita XSLT with good results on basic
transformations, which means it *might* (and that's a fairly big
might) be possible to produce fully searchable webhelp versions of
documentation with a reStructuredText source.  This is because
docutils has its own XML format which is able to be generated from
reST and perform the reverse to generate reST.  I have yet to see if
Don's project will go the other way and produce docutils XML from
DITA.

Fortunately for me, no decision even needs to be made until the GPGME
overhaul is complete and GPyGME final design decisions can be set in
stone.  Until then I get to keep trying things, listening to different
suggestions and trying to chart the most effective and uncluttered
course.

> When I refer to the man page, which is just one bloody long list
> without structure (and hence not a maze either), I use search terms
> to find what I look for. If specific ones will not do, a generic
> one, repeating the search until I find the option I want. Then
> again, by now I've referred to it reasonably often when trying to
> help people on this list or playing around.

Sounds familiar, when checking or double-checking anything I usually
check that the command I'm thinking of exists with "--dump-options"
piped into a grep and then check the resulting command or commands in
the man (or info) page(s) to confirm the right syntax or instructions.

Still, I only reached this point following years of practice with PGP
2.x, PGP 5.x, PGP 6.x, GPG 1.2.x, GPG 1.4.x and now GPG 2.1.x (I did
play with both GPG 1.0.x and 2.0.x, but kinda leap-frogged both of
them for general use).

 
Regards,
Ben
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 630 bytes
Desc: not available
URL: </pipermail/attachments/20160325/0bc535b0/attachment.sig>