Is a Deviation v4.1 release on the near horizon?

OK, manual work:

I gave up on Google Docs. It isn't up to the job.

It seems that LibreOffice has an Edit->Compare Documents feature. I used that to (try) and merge the changes in PB's manual repository into the team repository. While that's not as simple as doing a merge in a good VCS, it does work. The downside is that I wasn't sure whether a a difference was a change made in the team repo or by PB, so I picked those that I thought were best. Please review!

If we are reduced to asking for text changes, then some of the reasons for using LibreOffice go away, as we don't need those suggesting changes to be able to run the word processor. In that case, I would say that generating both documents (or do the new Tx's mean there are now more?) from a single source should be an important consideration.

Rst doesn't seem to provide conditional text, but sphinx seems to have an "only" directive that's been added via the extension mechanism. Personally, if we're going to go with a markup format, I'd vote either LaTeX or DocBook. LaTeX works well if you're willing to let it do the formatting - but the formats were designed by professional, and I find them absolutely lovely. As for DocBook, two decades of working with SGML has left me with a nice collection of tools that leverage machine readable schemas. So I can write valid HTML or XHTML or pretty much anything with an SGML schema faster than I can write markdown.

But for now, I'm going to see what I can do about using LibreOffice's conditional text facilities to merge the two documents. With an eye on making it generate one manuals specific to each supported Tx.

LibreOffice can processes .doc files. I have in the past used OpenOffice to collaborate with a group that was using Word. It occasionally hiccupped a bit on formatting, and some versions of Word would lock up Windows trying to load a file it produced, but loading and saving it in a different version of Word solved the problem. Maybe there's a format shared by Word and LibreOffice that would work well?

SGML wasn't meant to be written by humans in its raw form, and XML removed most of the features intended to make input by people sane. So without schemas and an editor that can leverage them, it's pretty much unbearable. But being familiar with those, I found the RST ecosystem painful. If someone wants to take the lead in converting and updating the docs, I'll be happy to proof read them and suggest changes, but have no interest in doing any heavy lifting in that environment.

I heard back from Indigo. He's just been tied up with another project. He's hoping to get back to deviation at some point, but isn't clear about when.

He's got three issues assigned that aren't related to the DSM or Devo work he's been doing:

1. Reordiring virtual mixers screws up any references to the mixer in other mixes. Possibly this happens to output channels - I haven't checked.
2. A Skyartect power issue. It looked like the CC2500 power issue PB closed recently might have been related.
3. Virtual mixers not updating in the mixer display.

I would suggest that we put the DSM stuff last in the release process. If he's not back when that's ready, we can deal with it then. Worst case, we release what's in default now as no worse than the last release. We might also try a release candidate that merges his code with default, if he thinks it's ready - I did ask him about that. Of course, the best thing to do would be for PB or someone he trusts to get familiar enough with his code to make an informed decision.

Yes, I have some experience with RST, as we build the documentation for our software with it ( docs.akeneo.com/ ). We use sphinx for that purpose. I think in case of Symfony, they used the Latex builder to generate their PDF.

In case of rst2pdf, it's an entirely different beast, as it has specific tags. But I use it from time to time to generate good-enough looking PDF from the comfort of my text editor
It allows some interesting styling as well. Once (and if) you have some code example, we could try to make some better styling that the default one. Not sure that it would worth the hassle to go through the Sphinx -> Latex -> PDF process. rst2pdf should be enough, and is far more easier to install and use than the full Sphinx suite.

Well, LibreOffice managed to screw up the 8 manual (it wouldn't load), so I redid adding your changes. That was actually pretty easy, and I could see doing this on a regular basis.

So I went ahead and fixed the two outstanding manual issues. Those were both artifacts from one manual (pressing screen areas in the Devo 10/7E manual, and talking about Ovals on combo buttons in the Devo 8 manual). These have all been pushed to the repository.

I didn't get to looking at doing a single document for both versions. Given the above, I think that's even more important. Will that be useful if you move to RST?

The idea isn't to have one manual, it's to have one fodt file that can be used to generate all the manuals. Ideally, one for each transmitter.

I started this by partially converting the Devo 10/7E/F7 manual to be what I had in mind. Didn't finish, because LibreOffice's Copy/Paste on tables didn't work, so I couldn't change the table at the end to one for each Tx without recreating it by hand. More work than I wanted to do for a demo.

You can check out the result in the deviationTx/deviation-manual TwoInOne branch. On the title page, you'll notice that the transmitter model number is now a field. Double-click on it, and set the value to either "7e" or "10". If it's set to "10", all the special notes for the 7e won't be in the document. If it's set to "7e", all the features that aren't supported on the 7e won't be there.

Unfortunately, libreoffice shows off it's inadequacies here in another way as well. If we can't figure out how to work around them, then we can't use this. I'll leave spotting it as an exercise for the reader.

Can't be done in LibreOffice. LibreOffice has a bug that hidden sections affect section numbers. So hiding the section on DataLog from the 7E means there is no section 7.3 (I think it was), and 7.4 follows 7.2. This bug was inherited from OpenOffice. In OO, it was done that way because Word did it that way, and when they looked at fixing it, decided that compatibility was more important than correctness until they had the resources to make it an option. As far as I know, it's still busted. This is pretty typical of my experience when using a word processor when I really needed a document processor.

FrameMake, TeX and DocBook all do this right, and have done so for as long as I've been using them. I expect RST will as well. But those are all document processors.

Whaoo, you skill up so fast on new stuff, that's scary

The PDF does look good, almost as good as the current Libreoffice doc. But are you going the sphinx way for both PDF and HTML ?

All great news!

Might I suggest that you name the chapters by title (or something indicating that), then use a "control" file that builds each manual by listing the chapters in order? While having the chapter ordering info in the title seems like a great idea, it means putting a chapter in different places in different manuals (for instance, if the new F* Tx's need a chapter on video in the middle) a problem. I've worked around that before if you really want to, but the solutions all boil down to keeping a list of chapters to build into a document somewhere. And once you've got that, having file names that communicate info to a human is a win!