Is a Deviation v4.1 release on the near horizon?
- mwm
- Offline
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.
- PhracturedBlue
- Offline
- Posts: 4402
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.
- mwm
- Offline
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.
- PhracturedBlue
- Offline
- Posts: 4402
Please Log in or Create an account to join the conversation.
- PhracturedBlue
- Offline
- Posts: 4402
Please Log in or Create an account to join the conversation.
- PhracturedBlue
- Offline
- Posts: 4402
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.
- mwm
- Offline
He's got three issues assigned that aren't related to the DSM or Devo work he's been doing:
- Reordiring virtual mixers screws up any references to the mixer in other mixes. Possibly this happens to output channels - I haven't checked.
- A Skyartect power issue. It looked like the CC2500 power issue PB closed recently might have been related.
- 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.
- PhracturedBlue
- Offline
- Posts: 4402
Please Log in or Create an account to join the conversation.
- BitOne
- Offline
- Posts: 40
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.
- mwm
- Offline
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.
- PhracturedBlue
- Offline
- Posts: 4402
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
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.
Please Log in or Create an account to join the conversation.
- PhracturedBlue
- Offline
- Posts: 4402
Please Log in or Create an account to join the conversation.
- mwm
- Offline
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.
Please Log in or Create an account to join the conversation.
- PhracturedBlue
- Offline
- Posts: 4402
Please Log in or Create an account to join the conversation.
- mwm
- Offline
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.
- PhracturedBlue
- Offline
- Posts: 4402
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
Please Log in or Create an account to join the conversation.
- PhracturedBlue
- Offline
- Posts: 4402
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.
- BitOne
- Offline
- Posts: 40
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.
- PhracturedBlue
- Offline
- Posts: 4402
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
Please Log in or Create an account to join the conversation.
- mwm
- Offline
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.
- Home
- Forum
- Development
- Development
- Is a Deviation v4.1 release on the near horizon?