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
signature.asc
Description: PGP signature
_______________________________________________ Gnupg-users mailing list Gnupg-users@gnupg.org http://lists.gnupg.org/mailman/listinfo/gnupg-users
