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

More
08 Jun 2015 20:55 #33654 by mwm
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.

Do not ask me questions via PM. Ask in the forums, where I'll answer if I can.

My remotely piloted vehicle ("drone") is a yacht.

Please Log in or Create an account to join the conversation.

More
08 Jun 2015 22:27 #33661 by PhracturedBlue
Replied by PhracturedBlue on topic Is a Deviation v4.1 release on the near horizon?
fyi. I liked the idea of using fodt format initially because it is easy to hand off a document between folks and preserve the images and whatnot. It is better than a compressed format that is incompatible with version control. But if the set of users editing the doc is small, it would be better to keep the images separate from the doc since it makes the file size much smaller.

I've never written anything in latex, so I can't speak to it. I also haven't used DocBook, but I would not be happy writing the docs in an SGML language directly. I like the concept of sphinx. Formal processing via python extensions would probably let us add any customizations we liked.

I hate LibreOffice's diff capability. it works opposite to what I expect, and it is hard to understand what you are looking at in the preview window. I have used it several times and always left frustrated. I have several times considered moving back to Word; when pushing the limits, it is much better than LibreOffice. But I really prefer using open-source tools.

Please Log in or Create an account to join the conversation.

More
08 Jun 2015 23:09 #33667 by mwm
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.

Do not ask me questions via PM. Ask in the forums, where I'll answer if I can.

My remotely piloted vehicle ("drone") is a yacht.

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 00:39 #33673 by PhracturedBlue
Replied by PhracturedBlue on topic Is a Deviation v4.1 release on the near horizon?
I already tried the doc->libre office thing. it is a non-starter. everything gets moved out of place and it makes a big mess that needs cleaning up.

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 03:41 #33683 by PhracturedBlue
Replied by PhracturedBlue on topic Is a Deviation v4.1 release on the near horizon?
I thought I'd play with RST/sphinx a bit. BitOne, do you actually have any experience with it? I downloaded the symphony-docs from git. but I can't build a pdf from it (no issues building the html though). I don't see from the rst files how they create the title page or any of the inline images. The pdf is obviously generated automatically nightly, but I am not sure how they do it, or even what source they use. the textfrom the 2nd page (license page) doesn't seem to be included from the book, and the text in contributing/documentation/license.rst is different than what is in the pdf.

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 06:11 #33688 by PhracturedBlue
Replied by PhracturedBlue on topic Is a Deviation v4.1 release on the near horizon?
Well, I built the 1st 2 chapters in RST (not using any sphinx stuff yet). It translates to PDF pretty easily, and I haven't tried any fancy markup to improve how it looks. tables, lists, images, page breaks, references all work ok.
I haven't tried floating images as yet. I really need to try chapter5 I think. That should showcase just about all the requirements for the manual.

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 07:04 #33689 by mwm
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.

Do not ask me questions via PM. Ask in the forums, where I'll answer if I can.

My remotely piloted vehicle ("drone") is a yacht.

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 11:38 #33705 by PhracturedBlue
Replied by PhracturedBlue on topic Is a Deviation v4.1 release on the near horizon?
I can''t explain the Skyartec issue, and am not sure it is real. The bug I closed was fixed a long time ago, but it isn't related to the one Indigo is talking about. Basically, the claim is that the range doesn't decrease linearly with power reduction. However, when I've used my power meter, I can see that power goes down with each step as expected. The difference between min and max is only 10dBm vs 20dBm with the other modules, (this is a factor of the CC2500), and my guess is that this is why the range doesn't seem to get low enough.

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 13:31 #33713 by BitOne
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.

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 15:18 #33716 by mwm
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?

Do not ask me questions via PM. Ask in the forums, where I'll answer if I can.

My remotely piloted vehicle ("drone") is a yacht.

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 16:14 #33718 by PhracturedBlue
Replied by PhracturedBlue on topic Is a Deviation v4.1 release on the near horizon?
I'm not sure I follow. Having a single manual would be really nice, but I can't imagine it working well with LibreOffice due to the difference in images/formatting. Feel free to prove me wrong.

I'm finding RST works very well for what it can do. It is just what it can't do that is killing me.

Here is my test pdf
it is basically chapters 1,2,5. I didn't even try to cleanup the stylesheet or add a cover sheet. Neither of those should be hard.

Basically everything works fine except for wrapping text around images. I just can't seem to figure out how to control the margins so that it looks ok.

If anyone is interested, here's the source as well. I run:
rst2pdf test.rst -s test.style -e inkscape --use-floating-images -o test.pdf
without inkscape it should still work, just the svg won't render properly.

A work-around would be to use tables, with the image in the right column and the text in the left, but that makes formatting really painful.

If I could figure this out, I'd be almost ready to commit to this solution (still need to try sphinx and how the conditional stuff works, but it seems like it should be pretty easy to pre-process if needed).

I am a bit scared that rst2pdf seems to be abandoned, but if it can be coerced to do what I need (or if I can get pdf generation through latex to work) I'll live with it.
Attachments:

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 16:21 - 09 Jun 2015 16:22 #33721 by PhracturedBlue
Replied by PhracturedBlue on topic Is a Deviation v4.1 release on the near horizon?
Of course as soon as I posted that, the obvious solution occurred to me. I just used imagemagick to add a left border to the image. Now it looks pretty decent.
Attachments:
Last edit: 09 Jun 2015 16:22 by PhracturedBlue.

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 17:54 - 09 Jun 2015 18:00 #33727 by mwm
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.

Do not ask me questions via PM. Ask in the forums, where I'll answer if I can.

My remotely piloted vehicle ("drone") is a yacht.
Last edit: 09 Jun 2015 18:00 by mwm. Reason: add missing quotes

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 18:21 #33731 by PhracturedBlue
Replied by PhracturedBlue on topic Is a Deviation v4.1 release on the near horizon?
Yes I understood your intent. I am just unconvinced that the manual can be made to look good when built that way in LibreOffice. I think it should be easier to do in RST, though I need to prove that 1st.

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 19:57 #33734 by mwm
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.

Do not ask me questions via PM. Ask in the forums, where I'll answer if I can.

My remotely piloted vehicle ("drone") is a yacht.

Please Log in or Create an account to join the conversation.

More
09 Jun 2015 23:08 - 09 Jun 2015 23:25 #33752 by PhracturedBlue
Replied by PhracturedBlue on topic Is a Deviation v4.1 release on the near horizon?
well...sphinx is pissing me off.
It makes the document look really nice in html, but it makes a lousy pdf (even though it is using rst2pdf). The problem seems to be that sphinx requires a toctree entry (so it can build references and whatever it does), but rst2pdf doesn't properly support the:numbered: property of the toctree.

I found a crude work-around that allows me to get the numbering working properly in pdf and in html, and everything seemed dandy.

Then I tired to create a conditional section. It appears that rst/sphinx has the same limitation as libreoffice. I can create a conditional section easily enough, but it doesn't end up numbered when it is enabled.

I'm about fed up with this. RST seems like it should be able to do what we need, but so far everything I've tried to do has been incredibly painful, the tools are not well maintained (I've had to manually patch them to make current versions work together) and now in the end, it doesn't seem to actually work as we need it to.

How about oxygen + docbook as an option? I didn't realize oxygen isn't open source. I'm not sure which editors would be appropriate. libreOffice can work with docbook files.
Last edit: 09 Jun 2015 23:25 by PhracturedBlue.

Please Log in or Create an account to join the conversation.

More
10 Jun 2015 03:56 #33755 by PhracturedBlue
Replied by PhracturedBlue on topic Is a Deviation v4.1 release on the near horizon?
After taking some time to ponder, I went back to Sphinx. I have learned how extensions work (at least a little), and I wrote one that breaks rst rules a little, but makes true conditional sections possible.

Basiclaly you do:
Common Chapter
==============

Common text here

.. ignoreunless:: devo7e

Devo7e Section
---------------------
 some devo7e stuff here

.. stop-ignore

Common section
-----------------------
this will be common again

Now that I'm learning how extensions work, I'm going to look into the sphinx TOC stuff and see if I can get rst2pdf to properly produce section numbers without the hack I'm otherwise using.

Please Log in or Create an account to join the conversation.

More
10 Jun 2015 07:56 #33761 by BitOne
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 ?

Please Log in or Create an account to join the conversation.

More
10 Jun 2015 19:51 #33797 by PhracturedBlue
Replied by PhracturedBlue on topic Is a Deviation v4.1 release on the near horizon?
Honestly, stack-exchange is an amazing resource. You can find answers to almost anything there. Finding a similar (though more limited) plugin gave me ideas about how to go about it.

I'm pretty close to committed to RST now I think. I'll buold the rest of the manual and see if I run into any show-stoppers. I do use Sphinx for both the html and PDF. I need to extension capabilities to manage the docs properly.

Here is a sample of a converged source creating Devo10 and Devo8 manuals. Only Chapter6 and the Title are properly merged (other chapters just have devo8 text and images). I have not cleaned up the templates yet so they don't really look like the old manual.

I've checked in the source under the 'rst' branch, but building it is probably impossible for anyone but me. It requires a custom rst2pdf. I need to figure out how to best handle that.
But if you are interested, take a look at the source here:
bitbucket.org/deviationtx/deviation-manu.../source/chapter6.rst

I'm not sure how to name the chapters. each one is in its own file. There is no requirement that each pdf has the same set of chapters (though currently I have it setup that way), but with the current setup adding a new chapter in the middle would rename all files. maybe I should name them with the chapter-title instead
Attachments:

Please Log in or Create an account to join the conversation.

More
10 Jun 2015 19:56 #33798 by mwm
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!

Do not ask me questions via PM. Ask in the forums, where I'll answer if I can.

My remotely piloted vehicle ("drone") is a yacht.

Please Log in or Create an account to join the conversation.

Time to create page: 0.073 seconds
Powered by Kunena Forum