On Fri, Mar 25, 2016 at 04:37:59AM -0400, Robert J. Hansen wrote: > > And that doesn't even get into the issues involved with selecting a > > format for producing the documentation in. Consider the following: > > Preach it, Brother Ben.
:-D > And it's not just about formats, it's also about targets, Right, possibly more about targets really since the purpose of documentation is to help the end users use the software, not to help developers tick a box on the feature list and say, "yeah, we've got (extensive) documentation, sure." [I do realise that saying that is sacrilege in some circles.] > because each of these formats works best with different targets. Do > we want to optimize for reading in a browser on a desktop? Read in > a mobile browser on a smartphone? What about reading on a tablet or > e-reader? What about dead-tree editions? How will we make it > accessible to the blind? How... All excellent examples, especially that last one (which is often overlooked by software projects until someone affected by it raises a bug). All of which, just in the asking, actually move things more in the pro-DITA direction since there are existing DITA transformations for XHTML 4 (strict & transitional), HTML 5, XHTML 5 (i.e. HTML 5 with XML), EPUB 2.0, EPUB 3.0 (which covers the DAISY Consortium's primary concerns with Accessibility), Docbook 4.2 & 5.0 (plus anything they can be transformed into, including a proven track record with dead tree versions), CHM output, ODF output, RTF output, Eclipse help output, PDF output (usually via a FOP or [X]HTML+CSS rendering) and with my setup there are three different types of WebHelp output (standard, mobile and one with builtin feedback/comments system, but the last needs to be built with SQL db support). For examples of dead tree versions of things made with either DITA or DocBook that actually sell, there's XML Press (not a huge surprise) and also O'Reilly Media (which uses the same editor I do, see below). For the EPUB files, results vary depending on which transformation and source is used, but all the output is better than anything produced with Pandoc, Calibre or Sphinx. Sphinx can't produce a validating EPUB 2, let alone EPUB 3; Calibre dumps everything in a single directory regardless of what it is, but still manages to produce validation errors (mainly in the XHTML) and can't produce EPUB 3; Pandoc can produce both EPUB 2 & 3, but cheats outrageously (say goodbye to all chapters, say hello to everything in a single XHTML file and hope the end user device recognises the markup defining what a chapter or section is). Whereas the D4P EPUB transformation will retain your project's directory structure inside the .epub zipfile and will produce a fully validating EPUB 3.0.1 file in almost all circumstances. The exceptions are if a smaller cover image is included to display in Apple iBooks, it will appear twice in the manifest and is easily fixed with a manual edit. The other issue is it currently uses XSLT 1.0, which can't convert the build system's time to UTC and this may cause issues depending on timezone, also easily fixed with a manual update or possibly scripted or running the build on a system set to UTC. For examples (other than me) of groups or orgs using the D4P EPUB transformation, the biggest one I can think of is HarperCollins. They did, after all, pay to have it done and didn't mind having it licensed the same way as the rest of the D4P project (Apache 2.0) and as freely available as both that project and the DITA Open Toolkit (they're both on GitHub). > And no matter which you choose there's always a sea of people eager to > tell you that you're doing it wrong. Yet ever so rarely are able to provide suggestions which meet all the requirements. No doubt there would also be objections to learning an entirely new XML syntax, but then much of the most common mark-up is very similar to HTML (e.g. b for bold, i for italics, u for underline, p for each paragraph), linking is a little different, but not hugely (i.e. <xref href="https://www.gnupg.org/"; scope="external" format="html">GNU Privacy Guard</xref>, links within the same project don't need the scope and format bits) and images also differ slightly (<image href="kitten.png"/> instead of <img src="kitten.png"/>). On the other hand, once the realisation hits home about how much content re-use is supported and being able to make document-wide changes with a little careful design (including conditional output generation based on things like, say, software versions or supported feature sets), some of that grumpiness might dissipate. Maybe. Well, OK, probably not. > It's very frustrating. Yep. In some respects it becomes even harder with an official GNU Project like GPG and its sub-projects as there's that additional requirement (usually) that all components must be licensed under the GPL or LGPL (of whichever versions are relevant). DITA itself is an open enough standard to qualify, it's an OASIS standard, but the defining implementation (see dita-ot.org) and most public specialisations, like DITA for Publishers (see dita4publishers.org), are deliberately licensed more permissively (both use Apache 2.0). My setup is even "worse" since it mixes some more proprietary stuff in the implementation (but that's primarily the editor and some components which usually have Free/Libre or Open alternatives, albeit with greater potential for frustration). As the DITA-OT relies on something I loathe (Java) and I was quite prepared to shell out a modest sum to get what I wanted (generating valid EPUB 3 files and editing them without breaking them, since Sigil can't), I ended up getting oXygenXML Editor (their idea of support is in my experience unparallelled: it extended to full support to a freebie trial version and included adding a feature within 24 hours of asking about it during said trial; first as a plugin and later as a built-in). Oh, yes, I can load any file I have open in oXygenXML in Emacs from within it and doing so automatically loads nxml-mode, it's even bound to the same key sequence as It's All Text! in Firefox. Still, without a GNU implementation of DITA, it's still possible to produce everything with the DITA-OT I've mentioned so far, except the fully searchable WebHelp output (the XSLTs are part of oXygenXML Editor) and possibly not the rest2dita thing (depending on which version of Saxon is which, I keep getting them mixed up, but I've got it working with Saxon-HE 9.6.0.7). I know some people might argue against the DITA-OT itself with the Apache 2.0 license, but then turn a blind eye to Markdown (BSD license) and since both are GPL compatible I'm likely to ignore that argument. I will, however, pay more attention to arguments in favour of accessibility issues (e.g. generating screen reader friendly material) and translation of material (that's actual translations, not merely piping said material through translate.google.com). Regards, Ben P.S. The schemas I mentioned a few days ago are now in the ben/xml branch of GPGME on the git server. Licensing is the same as GPGME plus Apache 2.0 because it can't hurt.
signature.asc
Description: PGP signature
_______________________________________________ Gnupg-users mailing list Gnupg-users@gnupg.org http://lists.gnupg.org/mailman/listinfo/gnupg-users
