ben at adversary.org
Fri Mar 25 09:12:41 CET 2016
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:
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
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
> 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).
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 630 bytes
Desc: not available
More information about the Gnupg-users