I've considered Qt Assistant (the old name, IIRC) in the past, but it was overkill and heavy. We definitely should have one single source for the generated docs, otherwise it's pointless. Things like "introduced in 0.12", "obsolete in 0.11", and "differences since 0.10" need to be there. If we set up online documentation, we need to maintain it carefully. I agree that MD should be the logical source these days. MkDocs looks great, and so does MD preview in Bitbucket. 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.
#Speedcrunch source code manual
And the manual issue came to my mind the same day you decided to post this.
As you may imagine, I've thought about all this through the years. Better poke some of you guys so someone actually reads it :) don't feel obliged to respond. There is probably not going to be the interactivity of the formula book (click on a formula to insert) unless we are very smart. 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. 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. Still, no one prevents us to build several versions of the documentation, and host them at different URL's. MkDocs does currently not support multi language documentations (but plans to do so in the future exist). Transifex allows to translate plain text (and thus MD I just checked), so we can use the existing infrastructure there. No need to juggle with individual strings, translators are smart enough to figure out what should be translated and what should be left untouched. If we conclude that a translation of the docs is necessary, I'd say we just translate the markdown source. This is where (I guess) the original trouble started. 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. We'll need a simpler theme than for the online version (no Javascript, etc.), but MkDocs can handle it. We again build it into HTML and use it in conjunction with the QT Help Framework. Here I figure we can use the same Markdown source, no need to maintain a second documentation for this. 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. It looks beautiful, and it is very customizable and easy to set up. It is specifically designed to create documentations by compiling Markdown into static HTML. 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. Online is where I would look first if I needed help. Online Documentationįirst priority, I think we should get an online documentation.
What alternative could there be? I have an idea that might be worth discussing. 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. That's my opinion at least, and seeing that no one has made an effort to start writing proves my point.
Unfortunately, writing the user manual inside a C++ file is a pain. 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). 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. make good use of the available features (again both online and inline),.be easy to deploy (inline help preferably included in the binary),.share the same source for both online and included help,.be easy to translate (at best: could be integrated with transifex),.be easy to maintain (should not require changes in many places),.be easy to write (common tools and markup language),.I think we can agree that, ideally, the documentation should IMO it is even more important to provide an extensive online rather than bundling a basic reader with the application itself. Lately I have been thinking quite hard about best to go at this. Speedcrunch is still painfully missing a manual.
0 kommentar(er)
