Speedcrunch online manual#
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įirst 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!Īlso I don't think we need all the fancy semantic tags of Docbook, and concentrate on writing instead. 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. If we don't use MkDocs, Bitbucket & GitHub & friends display MD just fine out of the box! Integrated Manual Everybody and their grandmother knows Markdown, so I am positive that it we could produce a complete documentation quickly, and maintain it. 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. Imagine placing the cursor on a function, hitting F1, and up pops the documentation of that specific function! Translations The QT Help Framework bundles everything into a single file, which we can even shove into the binary as a resource. 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. 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. Better poke some of you guys so someone actually reads it :) don't feel obliged to respond.
Speedcrunch online code#
#Speedcrunch source code manualĪnd the manual issue came to my mind the same day you decided to post this.Īs you may imagine, I've thought about all this through the years. 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.
0 kommentar(er)
