User manual

[Former user]

Originally reported on Google Code with ID 124

Implemented as templated translatable HTML pages to be browsed in the new
book dock window (see issue #122).

Reported by helder.pereira.correia on 2007-12-11 23:31:30

[Former user]

``` I would be interested in assisting with this in some fashion. ```

Reported by `goodtimetribe` on 2007-12-12 01:36:07

[Former user]

``` It would be very nice if you could write pages for it :) We need information on the application functions and constants and how to use the program itself, along with the less known features. I cannot find a way to contact you privately. Can you please contact me? ```

Reported by `helder.pereira.correia` on 2007-12-12 09:54:17

[Former user]

``` In svn there is currently a file in the doc folder called speedcrunch.docbook that currently validates and fits all the KDE documentation style guides. Just need to finish that document.

If you are interseted in helping me finish it please contact me: [e-mail] ```

Reported by `jjesse` on 2007-12-31 02:39:15

[Former user]

``` There is documentation (in Open Office format) ready, that describes in short the input syntax and the implemented math functions and operators. The current state of trunk (as of 2008-02-04) is the base of this doc. ```

Reported by `wolf.lammen` on 2008-02-04 09:47:31

[Former user]

Reported by `helder.pereira.correia` on 2008-02-15 00:53:41 - Status changed: `Started`

[Former user]

``` wolf.lammen,

how does the guide that is openoffice relate to the docbook file that i created? should i merge the two? ```

Reported by `jjesse` on 2008-02-15 04:08:22

[Former user]

``` JJesse: the OO doc is just a text deposit that Marco Wegner will later use to produce documentation with the KDE tools. If you two can work on that together, it would be very nice. ```

Reported by `helder.pereira.correia` on 2008-02-15 11:09:34

[Former user]

``` Good morning,

There curerntly is a speedcrunch.docbook file in trunk/docs if I recall correctly.

This is setup for the KDE doc way of doing documentation. I will be working on the

flight home today on merging some of the two documents both OOO and the .docbook file and will commit over the weekend.

Jonathan ```

Reported by `jjesse` on 2008-02-15 17:13:13

[Former user]

``` As I'm working on integration into the docbook file I noticed the OOO document is copyrited Wolf Lammen. By including his name in the author group section am I complying with the copyright? The speedcrunch.docbook file is copytrited Ariya Hidayat and am wondering if there will be copyright and other license issues for integration?

Jonathan ```

Reported by `jjesse` on 2008-02-16 01:33:41

[Former user]

``` If you copy more than trivial parts of my text verbatim, it would be nice, if I am mentioned. If there is only little connection to my text, then you may leave it out,

of course. The OO document is in no way related to the docbook, I just wrote a sort of manual,

which others may extend or use at will. If nobody creates another form of documentation, I will convert my file into a PDF and hand it out as part of the documentation, so users will have at least this.

```

Reported by `wolf.lammen` on 2008-02-16 20:24:30

[Former user]

``` Since Marco Wegner won't be available on time to take care of the DocBook manual and conversion tools, this is now skipped to 0.11. ```

Reported by `helder.pereira.correia` on 2008-03-22 19:57:53 - Labels added: Priority-High, Milestone-0.11 - Labels removed: Priority-Medium, Milestone-0.10

[Former user]

``` Made a bunch of changes to the document and it is doing really well needs to validate and will try and commit those changes.

Jonathan ```

Reported by `jjesse` on 2008-04-05 01:59:07

[Former user]

Reported by `helder.pereira.correia` on 2008-07-19 18:24:18 - Labels removed: Milestone-0.11

[Former user]

Added in revision 0c276d12

Reported by helder.pereira.correia on 2014-02-27 05:09:42 - Status changed: Fixed - Labels added: Milestone-0.12, OpSys-All, Component-UI, Usability

[Pol Welter]

Speedcrunch is still painfully missing a manual.

Lately I have been thinking quite hard about best to go at this. IMO it is even more important to provide an extensive online rather than bundling a basic reader with the application itself.

I think we can agree that, ideally, the documentation should

• be easy to write (common tools and markup language),
• be easy to maintain (should not require changes in many places),
• be easy to translate (at best: could be integrated with transifex),
• share the same source for both online and included help,
• be easy to deploy (inline help preferably included in the binary),
• make good use of the available features (again both online and inline),
• look reasonably good.

Current state

The current plan for documentation includes a DOCBOOK file (which for me pandoc fails to export nicely to HTML) and a simple framework, but without actual content. As I understand it, Helder decided to go the way he did for the sake of easy deployment (hardcoded in C++) and translation (the strings are translated as part of the application itself).

Unfortunately, writing the user manual inside a C++ file is a pain. That's my opinion at least, and seeing that no one has made an effort to start writing proves my point. The docbook is in a similarly miserable state: it hasn't been touched since 2009! For me, I had never even heard of Docbook before, and I surely am not comfortable with its syntax.

What alternative could there be? I have an idea that might be worth discussing.

Online Documentation

First priority, I think we should get an online documentation. Online is where I would look first if I needed help. Today many programs don't even feature an integrated help any more!

Also I don't think we need all the fancy semantic tags of Docbook, and concentrate on writing instead. Markdown seems like a good idea to me.

So I have come across MkDocs. It is specifically designed to create documentations by compiling Markdown into static HTML. It looks beautiful, and it is very customizable and easy to set up. Everybody and their grandmother knows Markdown, so I am positive that it we could produce a complete documentation quickly, and maintain it.

If we don't use MkDocs, Bitbucket & GitHub & friends display MD just fine out of the box!

Integrated Manual

Next up: the inline docs. Here I figure we can use the same Markdown source, no need to maintain a second documentation for this. We again build it into HTML and use it in conjunction with the QT Help Framework. We'll need a simpler theme than for the online version (no Javascript, etc.), but MkDocs can handle it. The QT Help Framework bundles everything into a single file, which we can even shove into the binary as a resource.

The QT stuff really sounds cool. Imagine placing the cursor on a function, hitting F1, and up pops the documentation of that specific function!

Translations

This is where (I guess) the original trouble started. If we conclude that a translation of the docs is necessary, I'd say we just translate the markdown source. No need to juggle with individual strings, translators are smart enough to figure out what should be translated and what should be left untouched. Transifex allows to translate plain text (and thus MD; I just checked), so we can use the existing infrastructure there.

MkDocs does currently not support multi language documentations (but plans to do so in the future exist). Still, no one prevents us to build several versions of the documentation, and host them at different URL's. On the integrated side though, I am pretty sure there is a way to get QT to handle the right documentation file according to what language is selected.

Downsides

If we do share the docs between online and inline version, we will also have to accept that there will be no difference in content. There is probably not going to be the interactivity of the formula book (click on a formula to insert) unless we are very smart.

This has become quite a long one. Better poke some of you guys so someone actually reads it :) @heldercorreia, @Teyut, @fk, @thadrien, don't feel obliged to respond.

[Helder Correia]

This was great writing, thanks Pol. As you may imagine, I've thought about all this through the years. And the manual issue came to my mind the same day you decided to post this.

I agree that the C++ solution is not great, but technically it was fantastic for a variety of reasons :) The macro language definitely helps, but we still have the need to compile for testing, thus far from ideal, I agree.

MkDocs looks great, and so does MD preview in Bitbucket. I agree that MD should be the logical source these days.

If we set up online documentation, we need to maintain it carefully. Things like "introduced in 0.12", "obsolete in 0.11", and "differences since 0.10" need to be there.

We definitely should have one single source for the generated docs, otherwise it's pointless. I've considered Qt Assistant (the old name, IIRC) in the past, but it was overkill and heavy. What's the current status of footprint? Yes, hovering on a function name and jumping to help would be awesome.

Yes, the docs absolutely need to be translated, that's not even arguable :) This is where an old tool I designed and asked an old contributor to write could come into play: https://code.google.com/p/ut3/ - the old website was generated using this (until I decided to make it pictorial, hated by many), and so was the formula book (until I decided to C++ it ;) See if you understand how it works. I'd much rather use this method again than having a full manual page as a translatable string.

I believe we could still have the formula book's click-to-insert-formula functionality with some work, not sure.

[Pol Welter]

I still think an online documentation would be great. Also adding comments to emphasize the differences of the versions sounds better than having to maintain one complete set of docs for each version. Even though version XY has been released a few years ago, it might still be worthwhile to adapt its online manual!

For the translation: as I see it transifex generates one string per line in the markdown file (see their desription on this). Obviously translators would have to figure out what has to be translated, and what not, but still, having the entire file for context might ease the task quite a bit (compared to a bunch of possibly randomly ordered strings). I am absolutely unfamiliar with Transifex in general though, so I might be on the wrong track here. EDIT: I have just found out that Transifex also supports .wiki files, which are essentially Markdown. One can upload .md files and choose them to be treated as .wiki files, which will instruct Transifex to identify strings in a smarter way. For instance it ignores single linebreaks in a paragraph, s.t. a paragraph will be treated as a single string. Here is a screenshot. This looks very workable!

In fact, I do not really care how the translated HTML's are generated; either by translating the markdown and building by MkDocs, or by building first, and then piping through UT3 or a similar tool. We'll have to see what is easier to use and more reliable :)

I agree that QT Assistant is overkill; instead I was thinking about displaying the HTML in a QTextBrowser as you were planning to do anyway. Essentially what the QT docs are describing here. It sounds fairly lightweight, and offers all the features we'd need.

Anyway, I am afraid I won't have to much time on my hands in the next weeks (exams are coming up), so don't expect a complete documentation anytime soon just yet :)

[Pol Welter]

So let me wrap up the pros and cons of translating the markdown directly vs using e.g. UT3.

About translating MD:

• Translators can work in situ, directly in the MD file, using their editor of choice (including e.g. spellchecking).
• The document is split into strings automatically by Transifex, but it will surely sometimes fail to do so in a logically coherent way.
• Translators might break the markup, or inadvertently change stuff that was not meant for translation (e.g. sample inputs).
• Authors need not worry about including the additional tags needed for translation.

About post-build translation (is that even a thing?) with e.g. UT3:

• Translators best use Transifex or whatever platform we offer.
• Strings might lack context.
• Since the original author alone is responsible for format, there is no danger of breaking stuff.
• Authors must manually mark the strings for translation. This represents more work, but gives us finer control about what to translate.

A note about the last point: Since Markdown has a pretty minimal markup overhead, translatable strings will cover about ~95% of the source. For instance consider something akin to this:

[...] Implicit multiplication is especially useful when using units. For example a = 5 meter + 10 yard will be interpreted as a = 5*meter + 10*yard. [...]

While it would logically make sense to exclude the code fragments from the translatable string, this will only fracture the document and make the translator's job harder. So I guess we'd just end up marking larger chunks than strictly needed, essentially covering the whole markdown document.

I'm not trying to convince you or anyone else, just laying out my thoughts.

[Tey']

For what it's worth, it seems Crowdin handles MD files much better than Transiflex: I've never really used it though, but I think that's what reddit uses and it's free for open source projects.

[Helder Correia]

"Translators can work in situ" - I don't see this as an option/advantage, honestly. This is one of the reasons why Transifex and Crowdin exist in the first place - Hide technicalities from translators and center the process in a nicely accessible web tool. "Authors need not worry about including the additional tags needed for translation." - I'm willing to insert those tags myself. Contributors don't need to worry about it. I think it's worth the trouble.

Crowdin looks better than Transifex with wiki interpretation, but I'm not sure how smart it would be moving to a new service (does it even support TS files?). SpeedCrunch is currently translated into 23 languages above 60% completion, half on 100%. I know the Transifex platform well enough to feel comfortable, not sure about Crowdin. One can argue that most translators are probably on all platforms and that we would still get them on the project, but it's just an assumption. The thing with UT3 is that it compiles all strings from all source files (manual and formula book) into a single PO or TS file. If we upload MDs directly for translation, it will mean as many translation sources as formula book pages out there. We can probably fit the whole manual into a single MD document though.

This being said, my current thoughts are not happy with moving to Crowdin, nor having multiple translation sources on Transifex (that even contain a bunch of code characters).

[Pol Welter]

"Translators can work in situ" - I don't see this as an option/advantage, honestly.

It was not meant as necessarily an advantage :). I am just not overly confident that extracting and substituting strings is the best way to translate a structured document. The approach works exceptionally well for a piece of software (how could you possibly do it differently) but for a manual... not sure.

So, I just briefly checked out Crowdin (they have a demo project available, where you can have a look at the features). They support pretty much every format under the sun (including MD, TS and of course PO). The interface is very nice; as someone not familiar with either Transifex or Crowdin, I have to say that I found my way around the latter much more easily. Still I agree that there has to be a catch (there always is!), and migration will very possibly be painful.

Can you expand on why you are against multiple resource files? Wouldn't logically organising the strings in multiple files make sense? IMO it is essential for the docs to be composed of multiple pages. I am not comfortable with squeezing the entire manual into a single file ( = page). It will be a nightmare to browse. Just to make sure we are on the same level here: I was envisaging a documentation including

• an introduction,
• a guide on how to install SC (this might not be trivial on every Linux distro!),
• how to use all the various features (like bitfield, quick insertion of constants, user functions, ...),
• a list of the integrated functions, a list of the integrated constants and units,
• and finally some guidelines & tips for future contributors.
• EDIT: And some more obvious stuff that I cannot think of now.

This will quickly outgrow a single page, plus some parts don't need be in the integrated help.

Also, can UT3 handle Markdown? If so, was your plan to translate the Markdown or rather the final HTML?

I was not taking about the formula book. That is another story; honestly I think it is embarrassingly useless. I was really excited about it at first, but soon calmed down. The one formula you need will never be in it (no matter how hard we try), and the ones that are included will have variables that are named differently, so you will still have some typing to do. Adding more formulas will just increase the trouble of finding the specific one you are looking for. Overall you are just better off googling it. But let's stay on topic ;)

As a final note: in the end it is your call. We'll follow your lead :P

[Pol Welter]

I just set up a temporary site for SC on crowdin to probe how easy it is to import what we already have: https://crowdin.com/project/speedcrunch If you are interested I can add you as collaborator. EDIT: Don't mind that not all the available languages have been imported. I just chose the default ones.

I fear not all the strings have been imported. Since the degree of completion cannot be compared to the one shown on Transifex (those are different versions than the ones from the repo, which I used), I checked with QT Linguist. E.g. for Portuguese (PT_PT) QT Linguist shows that all of the strings have been translated, yet Crowdin lists 12 as missing. Not good.

It looks though that these are just the strings that are the same in both languages (like 'Ytterbium')... Crowdin might fail to pick those up. It is difficult to verify this on other languages.

Either way, I find Crowdin much easier to navigate than Transifex. Justed wanted to say that.

[Pol Welter]

I just sent a message to the Crowdin people. Let's see what they think.

EDIT: According to their response, I just needed to flip a (rather obscure) switch when uploading the translation files. All working fine now.

[Pol Welter]

In the last few days I started writing a bit. I'll add an attachment with what I've got so far. It's loosely based on the old docs. (I think it's pretty clear where I got bored and stopped.)

Don't mind the theme of the rendered HTML, that is easy enough to change :) Have a look, tell me if that's the level of detail you were up to.

Anyway, if we do this documentation properly (and that's my plan), I estimate the amount of text it will contain will be at least 10x what we currently have to translate for the application itself. Is the community up for this task ? :P

Jokes aside, do you think that anyone out there will actually bother to translate the documentation? I mean, surely the five of us might manage to produce a translation in, say, Portuguese, French, German,... but the translation was to be a crowdsource business. I for sure would prefer to concentrate on other stuff than translation.

---

Also, I put some more thought into the possibility of a mkdocs build chain. I am positive it can be done. However it is slightly more complicated than initially thought; we'd require to write a custom build script (think makefile) and a tool to dynamically construct configuration files for each language. (QT and mkdocs will require config files to do their job; those will look almost identical for each language, so automatically building them from a template makes sense to me).

So far no problem though. Instead of 'click a single button' it now sounds more like 'write a small tool (~100 lines) and press a single button'. The real trouble is a shortcoming in mkdocs, that will prevent us to easily translate the table of contents. According to the devs, adding this feature is on the todo list, but I don't expect a solution anytime soon. Until then, we'd have to extend the above mentioned tool to also create the TOC by reading the translations from one more file.

That being said, I still think this is the best way to a scalable, easy to maintain documentation.

---

Finally back to the question of how to translate the MD: I think we should see to that question once we have the rest set up. As far as I can tell, Crowdin is a viable alternative to Transifex. They also have a CLI tool to manage the files, and they support MD very well. The existing translations can be imported just fine (once I knew what to do, it was like a 5 minute job).

@Heldercorreia, what is your argument against multiple source files? I'd love to hear your thinking, I am surely missing something there.

[Helder Correia]

@polwel No real strong argument other than convenience. From a translator's perspective, it's nice to focus on one single source, and knowing your overall progress status immediately. It is true that multiple files can provide some more context. Regarding a move to Crowdin, I'm still not sure about it. It's nice to know that they also have command-line tools for the workflow (do they work on Linux?), but I'm afraid of losing the amazing translator base conquered through the years. In my experience, I do believe they would translate the docs, no problem. And here maybe having one single source would help there again, I don't know.

[Felix Krull]

'k, I've been side-reading this bug for a while. I obviously agree with the basic things -- need for a manual, Markdown or similar, single source for web and bundled.

On to the build aspect, I was going to say how mkdocs looks good, but then I found out that Sphinx has localisation support built in (http://www.sphinx-doc.org/en/stable/intl.html). I haven't played with that feature in particular, but it might make Sphinx preferable to mkdocs with a home-grown translation solution:

• it would solve the dispute about the best way to translate the manual
• it doesn't have the TOC translation shortcoming that @polwel discovered with mkdocs
• it's a more widely-used, fully-featured, mature tool

A downside, arguably, is that reStructuredText is a more complex (if more expressive) syntax than plain Markdown.

I did have some opinions on how a home-grown solution with mkdocs would work, but I'll keep those back in favour of the Sphinx suggestion for now.

[Pol Welter]

Yes, I have also come to the conclusion that MkDocs is probably not worth the effort. It was vvery attractive thanks to its usability, but simply does not offer some of the features we need.

Hence Sphinx is the next candidate. At first I was blown away by its huge list of features, but it seems rather easy to use as well. All the features we'd need to provide on our own for MkDocs seem to come with Sphinx out of the box. Transifex is now perfectly fine. (For the record: I was not too comfortable ether with a move to Crowdin; don't fix what isn't broken. I just investigated it as a part of the new toolchain). I have never used Sphinx before, but as Felix says, it is so widely used, that it must be fine :)

RST is a no brainer for me. The increased complexity is more than compensated by its larger feature set. MD is actually slightly cumbersome at times when writing a more complex document.

---

On a different note, I have been experimenting with the QHelpEngine stuff. It adds fairly minimal overhead (~ 2MB to the binary), and allows us to display browsable HTML as our help. The styling needs to be reduced quite strictly, since we want to render it in a rich text box. We will have to produce a custom theme for Sphinx that only uses the supported tags, and - obviously - no javascript. Also the definition of keywords (i.e. the mentioned ability to jump to the docs of a given function) is very straightforward. I could get the site generated by MkDocs to work, so I am confident that Sphinx will also be ok.

Concerning multiple languages: This will work by creating one QHelp Project file per language. Unfortunately this means that also the list of keywords will have to be maintained for each language. But here I see an easy way to automatize the creation of the project files from a template.

[Felix Krull]

So Sphinx has a Qt Help builder (http://www.sphinx-doc.org/en/stable/builders.html). Just make qthelp. It seems to work fine. I think we have a winner, TBH. We'll probably have to massage a theme so it displays with QTextBrowser, but that should be a minor issue.

[Pol Welter]

I yet have to give Sphinx a shot, but that sounds amazing!

About the theme: I had cobbled together a theme that works for MkDocs. It looks okay, and I am confident we can reuse at least the stylesheet from it. If not, it wasn't too much work anyway... Most of the time I was trying to navigate the limitations of the HTML renderer of QTextBrowser. The most annoying restriction is that padding style directives seem to get ignored unless in a table. Makes the document look a bit flat, but I can live with that.

As you say, unless we discover something really unexpected, this is the way to go. Nice.

[Felix Krull]

For the record, I've used Sphinx before, without localisation, and I do really like it. My original thought was that it might be "overkill" for our use case, but it has all those nice features we need already, sooooo. I found this post from someone using Sphinx w/ localisation for software documentation (even with Qt, it seems) which sounds pretty positive about the whole affair.

I played with Sphinx's localisation some more. My preference originally would've been to translate the entire source documents, but Sphinx does it the extracting way and they use it to translate their own documentation, so I guess that's fine. One issue I've had is that the paths to the source files in the generated .pot and .po files are relative to the location of the .pot file, which means Qt Linguist can't display the source file for context when editing the .po files. Not sure if this is actually a problem though.

As for Sphinx and Qt Help, it really seems to work well. It even populates the keywords with the contents of Sphinx's index directives. It does generate one Qt Help Project and a Qt Help Collection Project per Sphinx run; I'm not sure if we want a collection per language or one collection for everything.

Ultimately, I think we'll still want a helper script for the doc build since we need to run Sphinx and qcollectiongenerator once per language at least. I say we just use a Python script for that. With Sphinx, we indirectly depend on that anyway, might as well use it so we don't have to handle that in the build system.

[Pol Welter]

Great, thanks for experimenting.

I played with Sphinx's localization some more. My preference originally would've been to translate the entire source documents, but Sphinx does it the extracting way and they use it to translate their own documentation, so I guess that's fine.

This also means we can stick with Transifex, which is great. Same as for MD, Transifex' support for RST is rather poor.

It does generate one Qt Help Project /and/ a Qt Help Collection Project per Sphinx run; I'm not sure if we want a collection per language or one collection for everything.

No, we want one collection file in total. That shouldn't be a problem to maintain by hand. I presume it hardly changes from one build to the next. All it does is keeping a record of all the languages, which is simple enough. qcollectiongenerator runs once for the entire documentation (all languages included). This is how I would do it. The other way (one collection file per language, essentially making them stand alone) will probably work just as well. The benefit of packaging everything into one collection is the possibility of cross-referencing between languages, and the possibility to share files, e.g. screenshots or images. The latter point is not an option anyway for now if Shpinx builds the project files though.

I say we just use a Python script for that. With Sphinx, we indirectly depend on that anyway

My thoughts exactly. Great!

[Helder Correia]

Now, this makes a lot more sense to me. One '.pot' colletion, sticking to Transifex. I like it.

[Pol Welter]

@heldercorreia Sorry, but we will still have one .pot for each page of the manual. We were talking about the .qhcp collection file, which Qt uses to keep track of all the help projects (i.e. localizations).

[Helder Correia]

Still, IIRC we can merge multiple pot's into a single one, no?

[Pol Welter]

No idea, you tell me :)

I'd prefer not to, since the pot's and po's are automatically created by Sphinx, and I doubt it will be happy if we merge them.

[Felix Krull]

Ok, to illustrate this discussion, I set up a branch with a Sphinx project, some initial documentation and some (empty) localisation files. In doc/manual, run make html to build the regular HTML version or make qthelp to build the Qt Help HTML and project files. (Needs Sphinx 1.3; unless we don't want to translate index keywords, that's going to stay that way.)

Edit: forgot the link ;) https://bitbucket.org/fk/speedcrunch/commits/branch/sphinx-manual. Also, make gettext to generate the .pot files.

(I'll refer to each set of .pot, .po and .mo file as a catalog; I think that's roughly correct.)

Sphinx generates one .pot file for the root document and one .pot file per entry in the root toctree (with gettext_compact=True). How we handle these files and the .po files is mostly our business, but as far as I can tell, Sphinx ultimately wants one .mo file per catalog in the locale directory, matching the templates it originally generated. So we could let Sphinx generate the .pot files, merge these for translation into a single file of doom per language, translate that, then somehow split it apart and compile it into the individual .mo files Sphinx can load. Qt's .ts files seem to support multiple catalogs (contexts) in a single file, so we could use that as the translation format. Seems possible, but pretty hacky ;) I'm not sure it's necessary anyway; the Sphinx project itself seems happy with one catalog per page: https://www.transifex.com/sphinx-doc/sphinx-doc-1_4/

I've experimented with importing the files into Transifex. It works as expected, but I'm a bit worried that it can't display the source ReST document; some strings end up lacking in context. D'you think that's a problem? (I don't have any experience with these translation platforms.)

@polwel With just one collection, wouldn't the content model that QHelpEngine gives us contain all the languages, so the TOC sidebar would always list all languages?

[Helder Correia]

I'm a bit worried that it can't display the source ReST document; some strings end up lacking in context. D'you think that's a problem? That's fine. The sentences are somewhat complex, they usually don't need context like the application strings (e.g. "Help").

[Helder Correia]

One .pot for each section is OK, I guess. I prefer that to hacking around beween formats.

[Pol Welter]

Ah right, I still had in mind that we'd use Qt's filter feature to blend out whatever we don't need. Again, now that the project files are build automatically, I guess we don't have to much control over the filters... One collection per catalog (I like that term) seems increasingly attractive...

About the TOC: we are providing the TOC as HTML anyway (main page), so why rely on Qt to generate it? Also if we render everything in a textbox, there is no sidebar.

I'm sorry I don't have time now to check out your work. Might do tomorrow.

[Felix Krull]

Generating the qhcp file isn't really a big deal. Let's just postpone that decision until we have a help browser so we can see what works best regarding collections, many, one or none.

Re TOC: there's QHelpEngine::contentModel which sounds like it's a model we can just plonk into a QTreeView to get a TOC. If that exists, might as well use it, right?

[Helder Correia]

Issue #591 was marked as a duplicate of this issue.

[Pol Welter]

Ok, I spent some time tinkering with QtHelp and Felix' toy docs. I tried to set up SC so it displays the HTML in the Manual window.

Conclusion: It works!! Kinda... Let me explain what I found.

Qt's linksForIdentifier function is amazing. Provided that the keywords are setup correctly, it allows us to jump to whatever feed it. Just call linksForIdentifier('cos') and there is the documentation of it. I see great potential for displaying help of functions, constants, etc. The problem is that Spinx' QtHelp builder does not populate the keywords' id field - which we require.

A not-quite-a-workaround consists in adding manual index entries to the .rst files, e.g. .. index:: Home. Normally these don't give the keywords an id either, unless you provide an additional parameter in parentheses:

.. index:: NAME (ID)

This will generate name="NAME (ID)" id="NAME.ID" in the keywords section of the .qhp. While now we have the id field set, this is still not brilliant. These entries will show in the index as well, so it will be cluttered with entries of the like cos (function). This is unfortunate since the index already contains references to all the functions, etc.

I am currently investigating how easy it is to implement a Sphinx extension that allows us to use e.g. a .. qtkeyword directive, that only generates an id (no entry in the index), and that is ignored by any non-Qt builder...

[Felix Krull]

Le sigh. It's always something, isn't it. Does linksForIdentifier only return keywords that have id set? If it also returns other keywords, it may be easier to just rename the index entries so we can refer to them from code (which would need a custom domain, but that shouldn't be too hard if we derive from the Python domain).

[Pol Welter]

That's the problem: the id tag must be set for the keyword to be visible to linksForIdentifier.

[Felix Krull]

Hm. Ok.

• In any case, we need to modify (== derive from and extend) QtHelpBuilder to generate id fields in a way that's useful for us.
• The problem with only-id index entries is that they'll invariably also appear in the HTML index in the QtHelp docs. We may want to stick to one index entry per function etc. and parse/"guess" an id value from the name.
• I'll probably add a custom domain anyway to nix the "(built-in function)" suffix. It's not technically wrong, but I fear it might be translated weirdly.

[Pol Welter]

Writing an extension for this is not easy. Either that or I am looking in the wrong place.

The problem is that by the time QtHelpBuilder steps on the stage, all the HTML has been generated (by the docutils writer); QtHelpBuilder merely packages the files and generates the help files from the index. I don't see any stage of the built where we can inject our code.

• When parsing the ReST, we don't know which builder (qthelp or html) is enabled. (Technically I can figure it out by querying Sphinx; but Sphinx pickles this stage, so when running another builder next, things go wrong...)
• When the docutils tree is parsed into HTML, we still don't know which builder is active. Plus here I really have no idea on how to cheat to figure it out.
• Finally the qthelp builder can only query the index. It has no idea of/access to the parse tree. Since we don't want the stuff to appear in the index, I don't see a solution here.

So best thing I can do, is a hacky solution where the result is different depending on whether you make html or make qthelp first... But then again, since we are likely going to use two sets of conf.py and _build folders (for embedded and online help) anyway, this seems okay-ish. EDIT: Ah, and we'd still have somewhat funny names in the index...

EDIT2: hmm, I got an idea...

[Felix Krull]

I'm currently using a single conf.py and a tag, sc_bundled_docs, that's passed on the command-line when building the docs for bundling; you could check for that. But the issue with everything appearing in the HTML index still remains...

[Pol Welter]

I have cooked up something that seems workable.

• Directives .. qtkeyword:: are expanded into .. index:: provided that ignore_qtkeywords = False in conf.py.
• A subclassed builder qthelp2 that can
  • understand .. index::NAME (ID)
  • recognize function entries in the index (like ieee754_decode() (built-in function)) and populate the id field with the function name. A similar feature for variables, constants, etc can easily be added.

This way we don't need to spam the index (just use the entries that are already there) and still be able to define custom keywords where needed.

Either way, this 'solution' isn't especially nice, but it does the job, and can be customized if we see the need.

EDIT: Helder, do you mind if I open a new branch for this here in your repo? I'd like to avoid the constant shoving around between two repos, which Hadrien and I witnessed recently. This way, Felix and I can have a common ground to work on. (Pull requests are a bit weird at this early stage...)

[Pol Welter]

Good news!

I did manage to implement the .. qtkeyword:: directive I had hoped for in the beginning. Problem solved! (As so often, in the end it wasn't hat difficult... I indeed was digging in the wrong direction.)

I will upload it to my repo, so you can have a look.

[Felix Krull]

Ah, I see, the "just dump it in the environment" trick. I'll pull from there and integrate it into the build process then. I'll see if I can set up a domain so that any .. function definition automatically places a keyword for the function name so we don't have to add these qtkeyword directives to every function. D'you want to concentrate on the "manual viewer" side of this endeavour?

[Pol Welter]

Great!

Yes, I'll have another look at the C++ side. Add some features beyond a mere proof of concept.

I have just tried your doc-tool. Very cool!

There seems to be a bootstrapping problem with your new .pro though. If there is no manual.qrc that qmake can include, qmake will fail, and hence I cannot build SpeedCrunch to produce that required manual.qrc. I think resources are not supposed to go into the build folder...

EDIT: For now functions are not a problem. The corresponding entries in the index are recognized and treated correctly.

[Felix Krull]

qmake does warn about the missing file, but it was building fine when I tested with qmake+jom. On the other hand, qmake+mingw32-make (and I assume regular make on other platforms) doesn't want to accept that <build dir>/doc/manual.qrc is the same as doc/manual.qrc. I added an extra alias target that seems to take care of that.

Edit: And re: the function names, part of the issue is that the built-in function etc. parts are translated by Sphinx, so we can't just match on those; I'll try to rig up something explicit instead.

[Pol Welter]

Ok, it's working now, except for one thing: `win32:PY_COMMAND = py, which I had to change to python. The py launcher is not installed on my system (python 2.7.11). IIRC the laucher comes with Python 3, so yeah... -.-

I am actually wondering if it's worth it to create the QRC when building the application itself. I mean, when I change the ReST, a rebuild of SC will not automatically trigger a rebuild of the manual. So I need to manually delete the doc folder in the build directory. At that point I could just as well run sphinx by hand...

What would speak against just generating the QRC from time to time by hand and including it from, say, \speedcrunch\doc\manual\_build-bundled\? AFAIK that's also the process for translations. EDIT: Yes, I do know, CMake handles this much better :)

@functions: Ah, right, did not think of translations...

[Felix Krull]

Huh, I thought py was bundled with newer 2.7 versions. I never add python to the PATH on Windows because it gets messy when you have more than one version. As for the build in general: use CMake, it knows when to rebuild :P I admit I spent much more time getting the docs build to work well with CMake and then just rigged it into qmake really quickly, focussing more on the "working" than the "working well" aspect.

And on unrelated status updates: I now have a SpeedCrunch domain with keyword+id generation and even an automatically generated function index page. So that part is coming along pretty well, just need to clean it up somewhat.

[Pol Welter]

Wow, you're advancing quickly :) I'll need to get up to speed.

I will check out CMake more closely.

[Pol Welter]

You might have noticed that Sphinx identifies the languages by a different id than Qt ('en' vs 'en_US'). We will probably need to make a lookup table for mapping those. Shall I include it in the C++ code, or do you think it would be beneficial to have doc-tool do take care of it, so that it generates files that have the correct name?

@heldercorreia what are the language ids that are most suitable for Transifex?

[Helder Correia]

IIRC, I did add one exception rule for a particular language in MainWindow::createTranslator() in order to make it work, please have a look. I used to hack src/resources/locale/.tx/config before, but not anymore. Transifex supports en, en_US, en_UK, pt, pt_PT, pt_BR, etc. So the limitations, if they exist, are on the Sphinx side as I understand it. Let me know if you need help removing the current manual widget logic.

[Pol Welter]

Ok, thanks. I will include a language map in C++.

Let me know if you need help removing the current manual widget logic.

Already done.

[Felix Krull]

(Re: qmake, I introduced an additional dummy target that causes Sphinx to always run now, that should be a bit better.)

Some quick experimentation tells me:

• For the language codes, we can use any string we want, even ones that blatantly aren't languages. So long as the folder name matches the language code that we supply, Sphinx will pick up the translations just fine.
• Sphinx does have included translations for its own strings which use short names like 'de'. However, ...
• ... if you specify, say, 'de_AT' in conf.pySphinx will fall back to 'de' if it doesn't have 'de_AT'. (That seems to be a built-in feature of Python's gettext module.) So that's good.
• Not so good: any language Sphinx doesn't explicitly know gets the default English search functionality (which is more specialised per-language than just raw string replacement). It may be possible to overwrite that though.

Edit: That's html_search_language in conf.py. Should be fine.

So tldr: we can just use 'en_US', 'de_DE' etc. for the docs without the need for a mapping.

[Pol Welter]

Great. I'll skip remapping languages then.

[Felix Krull]

...with the caveat that parts of the search page never translate and stay English if you use 'lang_COUNTRY' (the 'Search results' and 'Search finished, so-and-so-many results' bits). I may just open a Sphinx bug for this and let them figure it out.

[Pol Welter]

Update: The minimal infrastructure on my side is done. The manual can be browsed and is automatically translated when switching languages.

Felix will probably be aware of this, but for the record: QHelpEngine can not work with files that are stored as resources. Hence I need to deploy them before use.

Quick access to functions is not in place yet, but will come next. Also clicking a web link currently kills the display.

One pretty major thing though I was not expecting for sure: the setupData function of QtHelpEngine is quite costly; it freezes SC for a second or so. Once set up, it only needs to be called again when switching languages. Still it is called at least once before the manual can be accessed, which currently is done at start-up. I have to wait a good second or two between clicking the SC icon and having it appear on screen. No good.

I was thinking of delaying the initialization until we actually require the manual. That would not save us from the freeze, but at least we don't have it at start-up. Any better ideas?

[Pol Welter]

On the subject of qmake vs CMake: today I worked with CMake instead of qmake as I usually do. CMake is still black magic for me, but it looks indeed much more powerful. I agree that it seems like a waste of time to maintain both. There are however problems I currently have with each.

• I still don't manage to build statically linked binaries with CMake. It worked out of the box with qmake. Someone smarter than me will have to figure this out...
• Qmake has really some issues with the new help building system... The python detection mechanism is basically broken (Felix and I use different configs here) and I did not manage to come up with something better. Also the mechanism for building the manual itself is one very ugly workaround... I am grateful for Felix for diving into this, and it sort of works (most of the times at least), but... yuck.

[Pol Welter]

Actually, before going ahead with the 'Context Help' (as I will refer it to in the future), I'd like some opinions on how you'd like it to work.

• Shall it use the same manual window? Or rather a special widget?
• What should happen if we don't find a keyword? Nothing? Home page? ...?
• Keyboard shortcut? I'd say F1, but it's taken. We can't shift the available commands up one button, then F11 for full screen will get in the way...

[Felix Krull]

Felix will probably be aware of this, but for the record: QHelpEngine can not work with files that are stored as resources. Hence I need to deploy them before use.

I was not, actually. That's annoying.

I was thinking of delaying the initialization until we actually require the manual. That would not save us from the freeze, but at least we don't have it at start-up. Any better ideas?

Run it in a thread, I guess?

Have you tried, rather than loading the collection file, to create QHelpEngine with an empty collection and then add a qch file with registerDocumentation? Though if that has the same restrictions, there's not much benefit in that... I'm not particularly happy suggesting this now, but might we be able to get better results by ditching QtHelp? As in, what features do we want to use from it and would it be feasible to implement those ourselves? (Without worrying about the Sphinx/build side of it for the moment.)

Also the mechanism for building the manual itself is one very ugly workaround [...]

Are you referring to the stack of three targets? Because that's a flawless masterpiece. Nothing wrong with it.. ;)

[Pol Welter]

Run it in a thread, I guess?

Good luck!

Have you tried, rather than loading the collection file, to create QHelpEngine with an empty collection and then add a qch file with registerDocumentation?

Will try.

As in, what features do we want to use from it and would it be feasible to implement those ourselves?

1. Compressed files. Only ~50kB per language
2. linksForIdentifier

Now with the delayed loading it is not so much an annoyance anymore. Try it out. I'd say we stick with it.

that's a flawless masterpiece

xD

[Felix Krull]

Well, I'll go on record saying that I remain unenthusiastic about QtHelp. Still, at least it gets the job done so I guess we can stick with it for now.

Liking the context help though!

[Pol Welter]

I have to agree.

I purposefully buried the QHelp stuff under a layer of abstraction (ManualServer) which should let us incorporate our own implementation of QHelp's features without too many large scale design changes. But I don't plan on doing so now, so let's avoid this discussion. Unless you are feeling ambitious that is :P

Glad you like the context help! (Considering the minimal work required to implement, it's a really nice feature :)

Different matter: the docs need some better looks. The basic theme is still to heavy-weight for our needs (it comes with loads of javascript, ...). I suggest we roll our own. sphinx-basic seems like a nice starting point though.

Next up: Translations. Transifex needs to be set up for the new files. Here we definitively need a hand by @heldercorreia. Is it possible to set up files/resources on Transifex that are not yet open for translation? If not, it might be a good idea to try in a test project first. Also, I think Helder should add Felix and me as collaborators. Promise we don't break anything ;) I haven't yet had a chance to look in more detail into how Sphinx and Transifex cooperate, but AFAIK this article should guide us through. Seems straightforward enough :)

[Felix Krull]

Point 1: translations. As I understand it, with Transifex, you upload your untranslated string lists (so gettext POT files for the docs) to Transifex, the merging and translation happens on their end and you just download ready-to-use PO files and drop them into the right directory? doc-tool has the extract-strings command which extracts all translatable strings and generates the appropriate POT files. This does slightly more than just make gettext because it also extracts the strings for speedcrunch_domain.py; at some point, I decided I needed proper translated strings for some of the domain stuff. This includes e.g. the title of the auto-generated function index page. (The file in question is extra-doc-strings.pot, but that should be an implementation detail; it needs the same treatment as the translations for the actual documents and goes into the same directory.)

(There's also the update-translations command which updates the local translations from POT files. That seems to be Transifex's job, but if nothing else, it can illustrate the directory layout.)

The translated PO files need to go into locale/<lang>/LC_MESSAGES. They don't have to be explicitly compiled, Sphinx (1.3) will automatically compile them if necessary.

[...] AFAIK this article should guide us through

I tried the first few steps of the Transifex guide on that page and the generated .tx/config file looks correct, as far as I can judge. sphinx-intl even picked up on 'extra-doc-strings' which is nice.

==========

Point 2: themes. It's a shame that QTextBrowser is so limited in what it supports (I guess it's understandable, but still). A document rendered using the 'basic' theme without a stylesheet looked mostly the same between QTextBrowser and Firefox (with the exception of fonts and seemingly some margins), so we can probably get by with just creating a new stylesheet. The QtHelp archives don't seem to include any of the Javascript libraries (at least according to the qhp files) and there doesn't seem to be any residual Javascript in the HTML files. The only thing we might not want from the 'basic' theme is the search page (which requires Javascript), but as long as we remove any links to it, that's not a big concern either.

tl;dr, we need a theme based on the 'basic' theme with a custom stylesheet that works with QTextBrowser and without search.html, if possible. I'll take a look at that, but I'm not very good at CSS, so no guarantees.

[Pol Welter]

For reference, you can have a look at Helder's config file for the translation of the app itself. It is in src/locale/somwhere IIRC.

Yes, the basic theme is mostly ok. Only the top navbar requires some love. Possibly (!) add some color to admonitions. I had not noticed that all the javascript junk is not included in the qhp. That's good news.

[Helder Correia]

Anything is better than adding QWebEngineView into the equation ;)

Just don't forget to make sure the merging of the local and the transifex POs works as expected. When pulling the current translations from Transifex, this is trivially done by the tx command-line tool. But when extracting the current local strings from the latest doc sources and merging with the existing POs, this must be carefully done since we're not using lupdate but some gettextfoo. Then we just use tx again to push to Transifex and everything will be merged and just work. Let's experiment on a separate project for now.

[Pol Welter]

I have a spare Transifex project I used for testing markdown a few weeks ago. I'll add you as collaborators.

[Pol Welter]

Good news! I had goofed when deploying the qch files, so they would not always be overwritten with the newest version. Fixed it. Guess what: QHelpEngine is lightning fast now!

[Helder Correia]

Let's ship it!

[Pol Welter]

Progress report:

• Fixed performance issue.
• More writing. Integrated functions are ~50% done.
• Better, Qt-compatible theme: check.
• Dummy setup for Transifex: check, and proven to work. (Check out the main page in German.) AFAIK, to roll it out to Helder's Transifex repo, all we need to do is adapt the config.

Also: Felix, your doc-tools are awesome.

I am feeling pretty proud right now. Except for writing we are pretty much done.

Go check it out.

[Felix Krull]

I see we had the same idea of using HTML tables for layout purposes ;) I've also been working on a theme and I've got it to a point where it's not just functional but it also looks good. Given the constraints -- QTextBrowser speaks less CSS than I do -- I'm actually really proud of it. I've attached a sample build (its appearance in regular browsers is mostly representative of its appearance in QTextBrowser).

So, with that in mind, I'm planning to release this theme on its own on PyPI; a relatively attractive Sphinx theme designed for QTextBrowser sounds sufficiently generally useful for that (disregarding the fact no one's done it before, apparently). Should we then:

• leave a copy of the files in the SpeedCrunch repository, bundled, or...
• ...have it as an external dependency, to be installed via pip?

---

Good to hear you fixed the performance issues though.

[Pol Welter]

Very nice, I like it a lot.

A few comments though:

• Cross-check this underline/overline effect with other fonts. Looks very cool with some light SF fonts like MS Reference. A more heavyweight font though... Currently SC displays the help with the same font the user selected for the main display. Either way it will depend on the OS.
• I'd go with some subtle background color on code blocks. I'll still have to see it in Qt, but IIRC Qt is not happy with paddings, so this will ease the task of seeing what belongs to the code box.
• Really like the colorscheme of the code highlighting. I guess it is intentional? :P
• Not sold on the background color of admonition text. Maybe leave the background white, but color the text the same as the title?
• Anyone not using it with the stringent constraints of Qt will appreciate an em {padding-right: 1px}.

Don't mind me, it surely is a matter of taste!

Don't hesitate to publish the theme. If it easily customizable (which the CSS part surely is), it is a no-brainer to grab it from pypi rather than from the local repo. Let us tune it bit more first.

[Felix Krull]

Cross-check this underline/overline effect with other fonts

I went through some of the fonts I have here and most of them looked at least fine with the lines. Re: fonts though, for my QTextBrowser test program, I've been using this piece of code to select a font:

QFont f("Helvetica");
f.setStyleHint(QFont::SansSerif);
f.setPointSize(12);

That has given me sans-serif fonts that should be more suitable for content vs. UI (Arial on Windows, Nimbus Sans on Kubuntu 15.10).

I'd go with some subtle background color on code blocks. I'll still have to see it in Qt, but IIRC Qt is not happy with paddings, so this will ease the task of seeing what belongs to the code box.

Well, you're right that QTextBrowser doesn't support padding (outside of tables...), but margins work fine. The code blocks look the same in QTextBrowser as they do in a proper browser. I did play around with a background colour for the code blocks, but ultimately decided against it because I felt it might be overpowering on pages with many code blocks and because you end up with these code samples with like 20 characters per line and this block of colour extending past the code all the way to the edge of the page; it looked a bit weird.

The syntax colour scheme is called 'trac' and included with Pygments. I simply went through their offering and picked one that looked appropriate ;)

Anyone not using it with the stringent constraints of Qt will appreciate an em {padding-right: 1px}.

? Is that doing something non-obvious? I'm not sure what you're referring to here.

Not sold on the background color of admonition text. Maybe leave the background white, but color the text the same as the title?

Y'know, I think I like the look as it is. Many of the visual aspects (all the colours and some other bits) are configurable from conf.py via html_theme_options, so if y'all think some aspect needs to be changed, that can be arranged; but I'll stick with the current settings as defaults.

[Pol Welter]

Margins are supported?! How could I miss that... That's great!!!

Forcing a font seems a legit solution.

Y'know, I think I like the look as it is.

As I said, it's a matter of taste. Don't feel obliged by my opinion.

em {padding-right: 1px}

Emphasized text spills into the letters to the right of it. Have a look at functions with multiple arguments, e.g.binomcdf(max; trials; p). Nothing we can do in QTextBrowser (I think), but in real HTML it'd be easy to fix.

[Felix Krull]

Emphasized text spills into the letters to the right of it

Sorry, I'm still not seeing what you're talking about. This is what such a function looks like for me (Windows 10 64bit, Firefox 45b6 64bit, Times New Roman):

This is with QTextBrowser (Qt 5.5 I think, Arial 12):

Sure, it's tight, but not unreasonably so.

---

In any case, I've now uploaded an initial release of the theme to PyPI and switched the doc build in my branch to use that. Get it with pip install quark-sphinx-theme; it lives at https://bitbucket.org/fk/quark-sphinx-theme. I've also been doing some minor polishing on the manual window (fonts etc.); I think in terms of outstanding issues, we're now at:

• (any more style changes, if my defaults get outvoted ;) )
• The keybinding for the context help; I'd love for it to be F1. We could re-assign all the number formats to Ctrl or Shift +Fx?
• the actual writing

[Pol Welter]

Ah ok, I had noticed it with MS Reference SF (standard font for Windows dialogs), in Firefox:

Ignore what I said. Yours look very much ok. Let's roll with it.

Like the name as well. Is it the elemental particle or the cheese? :P

For the keybinding, I actually was wrong the other day. F8 is not bound to anything. So we can just shift all the buttons F1 to F7 up one notch. I'd prefer to avoid modifier keys, as on some laptops, you already need to hit Fn to access the functions keys at all.

[Helder Correia]

Couple notes, in case someone else is on Ubuntu 14.04 and falls into the same issues I've been through: 1) Install qttools5-dev for find_package(Qt5Help) to work. 2) Point /usr/bin/qcollectiongenerator to your custom Qt 5.5 binary.

[Helder Correia]

Is this what you guys were talking about some posts above? Google Chrome (left) and SpeedCrunch (right):

[Helder Correia]

Usgin QMake for the build is not working for me, I believe because of manual2.target = doc/manual.qrc:

WARNING: Failure to find: doc/manual.qrc
.../rcc: File does not exist 'doc/manual.qrc'

[Felix Krull]

Re: qmake: does it actually not work? It warns that it can't find the file -- and it's not wrong -- but when you build, it should sort itself out.

Re: CMake: it seems qcollectiongenerator is in qttools5-dev-tools on Ubuntu 14.04; even then, it'll still pick up /usr/bin/qcollectiongenerator from qtchooser -- you can pass -DQCOLLECTIONGENERATOR_EXECUTABLE=/usr/lib/x86_64-linux-gnu/qt5/bin/qcollectiongenerator (for 64bit) to CMake. In general, for finding configuration variables for CMake projects, I cannot recommend cmake-gui enough.

---

Re: that layout thing. Huh. That's a problem. It looks correct (i.e. like in Chrome) for me on Windows with Qt 5.2.1 and 5.5.1; Kubuntu 15.10 with packaged Qt 5.4.2, qt.io 5.2.1 and 5.6rc. However, it looks like wrong (i.e. on the right) on Ubuntu 14.04 with the packaged Qt 5.2.1. I'll test Ubuntu 14.04 w/ qt.io 5.2.1 once that's downloaded.

Apparently that version of QTextBrowser doesn't handle margins (at least margin-left) and background colour on <pre> elements, or maybe anything that contains a <pre>. However, it can use those attributes on <div>s because the warnings etc. still work... It seems Canonical broke it.

[Helder Correia]

I get infinite blocks like this:

$ make
python /home/helder/dev/speedcrunch/src/../doc/manual/doc-tool.py --source-dir=/home/helder/dev/speedcrunch/src/../doc/manual build-bundled-docs --build-dir=/home/helder/dev/speedcrunch/qt55qmake/doc
usage: doc-tool.py [-h] [--source-dir SOURCE_DIR]
                   [--sphinx-build-binary SPHINX_BUILD_BINARY]
                   [--sphinx-intl-binary SPHINX_INTL_BINARY]
                   [--qcollectiongenerator-binary QCOLLECTIONGENERATOR_BINARY]
                   {extract-strings,update-translations,build-standalone-docs,build-bundled-docs}
                   ...

positional arguments:
  {extract-strings,update-translations,build-standalone-docs,build-bundled-docs}
    extract-strings     Extract translatable strings into POT files
    update-translations
                        Update the PO files for all languages from templates
    build-standalone-docs
                        Build stand-alone HTML docs for all languages
    build-bundled-docs  Build Qt Help docs for all languages

optional arguments:
  -h, --help            show this help message and exit
  --source-dir SOURCE_DIR, -s SOURCE_DIR
                        Documentation source directory (default:
                        /home/helder/dev/speedcrunch/doc/manual)
  --sphinx-build-binary SPHINX_BUILD_BINARY
                        sphinx-build command
  --sphinx-intl-binary SPHINX_INTL_BINARY
                        sphinx-intl command
  --qcollectiongenerator-binary QCOLLECTIONGENERATOR_BINARY
                        qcollectiongenerator command
/home/helder/dev/qt/5.5/5.5/gcc_64/bin/qmake -o Makefile ../src/speedcrunch.pro
WARNING: Failure to find: doc/manual.qrc
/home/helder/dev/qt/5.5/5.5/gcc_64/bin/rcc: File does not exist 'doc/manual.qrc'

[Felix Krull]

Ok, I figured out both of those.

I get infinite blocks like this:

Turns out doc-tool wasn't working correctly with Ubuntu's Python 2.7.6 because argparse had a bug/particular behaviour that was fixed/changed in later 2.7 releases so it never came up for me. Though, note that since you can't influence which qcollectiongenerator is used with qmake, you'll have to set the QT_SELECT=5 environment variable so /usr/bin/qcollectiongenerator from qtchooser picks the right one.

---

The layout issue is more interesting. I observed the same broken layout on qt.io Qt 5.2.1 on Ubuntu 14.04, even though it was fine with the same binaries on Kubuntu 15.10. I'm tempted to just leave y'all guessing because it's so stupid, but: it's Pygments. My host system had Pygments 2.1.0, my 15.10 VM an even older one. My 14.04 VM was freshly set up so it had Pygments 2.1.1. As it turns out, Pygments 2.1.1 has a particular change that inserts an empty <span></span> after an opening <pre> tag. And QTextBrowser 5.2 doesn't like that markup at all.

Qt 5.3 seems to have fixed that issue, so this layout problem only happens with the particular combination of Qt 5.2 and Pygments > 2.1.0. As such, I vote we document and then ignore it.

[Helder Correia]

Hmm, interesting. I'm on Ubunutu 14.04, Qt 5.5 and Pygments 2.1.1. I was confused when you said Qt >5.2 fixes it. I just rebuilt and rerun everything and I don't see the issue anymore. I was probably using Qt 5.2 indeed somehow... Also, I'm on Python 2.7.6 indeed.

[Pol Welter]

Hats off for figuring that out.

I have tried your theme in Qt, and it really looks amazing. I had not expected that the embedded theme would acually end up looking that nice.

Not exactly following what the trouble with qmake is again, but what about just getting rid of building the manual with qmake? Sure enough, CMake handles it nicely, but I wouldn't mind if qmake required a manual build of the docs first. As I said, the translations of SC require a similar manual action. Just put a static build of the docs into, say, doc/manual/_build_embedded, and update it once in a while by manually running doc-tool.

Point is, qmake choosing the wrong commands (python, qcollectiongenerator) is quite annoying. Maintaining the .pro to correctly build the manual will be a major pain (it already is).

[Felix Krull]

I massaged the docs build a bit more, for both qmake and CMake. The commands qmake uses are now configurable, with the following variables on the qmake command line:

• PYTHON_EXECUTABLE=<...>
• `QCOLLECTIONGENERATOR_EXECUTABLE=<...>
• SPHINX_BUILD_EXECUTABLE=<...>

Both CMake and qmake should now much more consistently choose the qcollectiongenerator binary for the Qt version you're using (by default, can still be overridden). I also moved back the result format keyboard shortcuts so context help can be F1.

@polwel So you checked out the Transifex/translation aspects and they work as they should, right?

---

So, I think that's everything in terms of infrastructure. Shall I open a PR? And, of course, how do we organise the writing?

[Helder Correia]

@fk Definitely open a PR and move the discussion there. Amazing work. Please also include @teyut and @thadrien as reviewers in addition to me and @polwel.

[Helder Correia]

Couple things I found while testing this: 1) Pressing F1 after launch has no result, but pressing F1 after opening and closing the context help first (and while not hovering any keyword) results in showing (raising) the manual window.

2) By default, the manual window seems to be shown maximized. While it appears to be OK, in reality it becomes annoying, reason being two-fold:

a) It doesn't jump to the correct line after pressing F1. The correct section is always located somewhere above (hidden). It works perfectly when not maximized.

b) I can't Alt-Tab to go back to the calculator unless I move the window away with Alt-Mouse. This may be Ubuntu-specific thing though. The manual is more likely to be useful when smaller than the main window, or about the same size but side by side.

[Pol Welter]

Hi, thanks to y'all for reviewing. Had no time to take a look at it yesterday. 1), 2) don't happen on my side. 2a) is annoying indeed. Weird. 2b) I think Felix (or possibly me, can't remember) changed something so that the manual is not displayed as a second window in the taskbar (on Windows that is). Could that be related?

[Helder Correia]

I meant that the manual window is opened maximized when the main window also is already. Does that not happen for you either?

[Helder Correia]

About the Alt-Tab issue: the manual window is actually always on top (which I can live with, but not sure it should be the behavior). So when both are maximized, the user can't see the main window again. (This is on Ubuntu)

[Helder Correia]

Any technical or otherwise reason why we shouldn't turn the manual window into a dock widget?

[Felix Krull]

@heldercorreia No technical reasons, but I'm not sure having the manual as a dock widget is that great. All the other docks can work well in a relatively small sidebar, the manual not so much.

The manual-always-on-top is because I set the manual window as a child window of the main window; which has other advantages, but I agree it's annoying that it's always on top.

[Pol Welter]

I agree with Felix. Having the manual as a dock sounds neat, but I prefer the current way. It allows the user to quickly open the manual with F1, and dismiss it with ESC.

[Helder Correia]

Shall we turn it into a non-child window then?

[Helder Correia]

Issue #187 was marked as a duplicate of this issue.