Sneak Peek: CoolBasic V3 manual

In parallel to compiler development, I have been designing the future-coming CoolBasic user manual for the past few weeks. I still use nearly 100% of developing time on the compiler, but the technical solution for the user manual is something I should keep an eye on as early as possible. Nothing too fancy, but I think it’s decided now how I’ll implement the manual (I have a working prototype already). Just like in the current version, the new manual will also be based on webpages. The exact same manual will be accessible both online and offline. You will be able to choose which version is the default when you access the manual from the editor. This way the end user can see always up-to-date online version if he/she chooses so, although the offline content will be updated regularly as well. It’s still uncertain whether or not those users who have a forum account, could write comments on the online manual pages.

Since the exact same manual is also available online, I must ensure that it’ll render the same way on all of the popular web browsers. This has been given me some headache. The offline manual relies on Internet Explorer WebBrowser control anyways, but as it’s well-known fact, IE doesn’t really follow the standards very well – especially IE6! A fresh statistics on StatCounter.com indicate that 1/4 of all Internet users worldwide still use IE6 as their primary web browser. Basically this means that the manual must support atleast IE6. This sets some limits and workarounds I have to consider when I design the CSS and the dynamic functionality for the manual. I test the manual with IE6, IE7, IE8, Opera 9.6, Opera 10, Firefox 3.0 and Safari 4. For some reason, I couldn’t be arsed to install Google Chrome yet. Also, BrowserShots.org comes to good use.

There’s always atleast one browser that fails to function like the rest. IE defines its own standards, naming attributes differently in javascript. Some browsers just function differently in some javascript cases, for example the “name” or “id” attributes combined with “getElementByName”. Frames render differently no matter how you define the borders. And then there’s Firefox that refuses to disable escaping in XSLT despite all the whine that has been roaming for several years now. Due to all this, I had to write some “hacks”. But atleast it works now. Why can’t all browsers just follow the darn standards! Why must they define their own rules that only apply to them and not to any of the rest!

Enough whining, let’s talk about something else… like the looks of V3 manual! There will be a treeview. The manual will be hierarchical. As opposed to the current manual, you can now see the entire path to the currently open page, as well as easily change to other articles that belong to the same context. The treeview operates in an intelligent manner, making sure the expanded listing will not grow too big; only the relevant contents will be shown, the rest of the pages always remain collapsed. Some users, however, like to browse the treeview with several separate parent nodes open at the same time. This isn’t possible because of the intelligent collapsing (and it’s intended), so to help browsing back, there is a “breadcrumb”-like collection of recent pages at the top side of the manual. This collection updates dynamically, reorganizing itself so that duplicate elements don’t appear.

The color scheme will probably be the same as the current coolbasic.com placeholder website (it looks so cool) with black background. I’ve made some minor improvements to the style sheet so that the layout fits better for manual pages. Captions will be aligned to the left, and their colour is now Orange. Links will remain blue. Text is still light silver. Emphasized text is now bright white and bold as opposed to current orange colour. In other words, every colour has it’s own, unique meaning. The test pages I have look very good at the moment. I also tried pastel colours with white background, but somehow it doesn’t look as good. The code editor will have white background, but this doesn’t fit to the dark theme of the manual. Therefore I’ll have to reconsider the source code colours for manual pages. More about that later.

Although the prototype is there, I won’t provide a screenshot just yet. There’s still tweaking to be done. I’m probably going back to 100% spent developing time on the compiler.

Comments are closed.

Copyright © All Rights Reserved · Green Hope Theme by Sivan & schiy · Proudly powered by WordPress