Documentation file format

John Ralls jralls at ceridwen.us
Sun Dec 15 11:03:46 EST 2013


On Dec 15, 2013, at 5:13 AM, Geert Janssens <janssens-geert at telenet.be> wrote:

> On Saturday 14 December 2013 23:05:14 Christian Stimming wrote:
> > Am Samstag, 14. Dezember 2013, 13:58:43 schrieb John Ralls:
> > > Well, the friendliest format for documenters is Microsoft Word,
> > > since pretty much any word processor will read it. We’ll get a lot
> > > of noise from the Open Source fanatics though.  Shouldn’t be too
> > > hard to make a toolchain to convert it into whatever distribution
> > > formats we want. Complexity there isn’t an issue because devs
> > > handle releases.
> > 
> > But any format of the OpenOffice / LibreOffice variants would do as
> > well. I don't consider Microsoft Word (btw: which version? 2005 doc?
> > 2012 docx? or whatever?) in itself a better alternative, but any
> > WYSIWYG processor that is reasonably well available on the various OS
> > is fine.
> > 
> > Regards,
>  
> Not something a non-dev care much about, but I do: how scm (as in software-change-management) friendly are those WYSIWIG processors in general ? Can you look at diffs between office documents ? Can you cherrypick changes between release branches ? Or even if you make a one line change will the saved file only reflect that one line change or will it reorganize the complete file ?
>  
> I would like to see a more non-tech friendly solution, but it should still remain something that can be managed. The idea is to attract more contributors, so the tool must be able to deal with concurrent changes.
>  
> To return to an earlier idea: there are WYSIWYG front-ends as well for wikis. The underlying data is still in wiki format, but the user only sees a fairly comfortable interface.
>  
> Or if we want to stick with docbook, I searched for docbook wysiwyg. Most editors are proprietary and pricey. But there is also serna-free [1], which claims to be a near wysiwyg editor that can handle docbook 4 (according to a nabble thread from last year August [2]). I haven't had time to experiment with it though.

The newer XML (docx, ods) formats should be less scm-hostile than the older binary ones like doc, but I don't know for sure that they guarantee that everything stays in the same order from one invocation to the next.

I'll take a look at serna-free after I finish the release, which unfortunately didn't get tagged last night because of problems with code.gnucash.org.

Regards,
John Ralls




More information about the gnucash-devel mailing list