[Ktechlab-devel] Some brainstorming...

[David Saxton]

On Monday 16 January 2006 19:46, Thomas Winkel wrote:
> Am Freitag 13 Januar 2006 01:06 schrieb David Saxton:
> > I'll see if tables can be implemented easily as well.
>
> Tables would be nice, at the moment it is not even possible to edit
> existing tables created in an external html program.
There doesn't seem to be any easy way to edit tables.

> > How I imagine the context help editor working is thus:
> >
> > * All the strings from the items are extracted and placed in
> > "context_help_de", etc, files (this can't be done until the latest
> > translated strings are being used - so I don't want to generate the files
> > yet if anyone is translating any context help.
>
> Ok, but from now I will place part descriptions in .htm files, named as the
> described part, or what are your plannings? Where should I store this
> (German) files? ./doc/context_help/de/ ?
I think all the help should be stored in one file for each language; this 
makes it easier to keep track of it all (else there will be several hundred 
files for various languages).

I'll create a directory - "./src/contexthelp" (./doc/ is reserved for docbook 
compilation into html and pdf documentation like in 
ktechlab.org/documentation/).


> > * It might be useful for people doing documentation to have a subversion
> > account, so that the descriptions in different languages can be kept
> > up-to-date with each other.
>
> If you are not afraid, I may damage something... ;)
That's the magic with version control - all information is stored, so any 
damage can be reverted with a "svn revert".

> * At moment KSpell checks the html source and not the viewed text.
Hmm...interesting. As far as I can tell, I have no control over KSpell; it 
just comes as an added "bonus" of using that particular KDE widget.

> * Bold, underline and Italian could be stored in one "popup icon" in order
> to make place for other functions.
I've put some functions into popups; bold, etc can remain as buttons until 
more functionality is implemented.


> * When text changed ktechlab should ask to save it when the user clicks an
>    other object.
I've changed it so that the context help is not reset when the user clicks on 
another object if the text has been changed.

> * There may be a switch between html source and preview.
> * The result looks different from konqueror, there are some spaces missing
>    and the formula should be red on gray background and centered.
>    How can this happen? I think both uses khtml... (see screenshot)
At the moment, ktechlab's context help uses Qt's basic html viewer. Using 
KHTML is very easy though - I'll have a look at it.

> * There may be a "back" buttom while browsing which goes inactive when the
>    selected object description is shown. I have some further links in my
>    descriptions which may also be accessed from other objects (see
>    screenshot). Or is there a html solution for doing that?
> * I have some external links, these should open in an external browser. At
>    moment a blank page is shown and the only way back is to reselect the
>    object.
> * Could you provide a way to open example circuits, flowcode, etc. from
> help?

All very easy to implement with KHTML - the application gets notified when a 
URL is clicked on.

* For example circuits, etc., how about "ktechlab-example" for a protocol? (so 
e.g. "<a href="ktechlab-example://help/opamps1.circuit"> will open up 
something like "/usr/share/apps/ktechlab/examples/help/opamps1.circuit").

* For links to other objects, how about "ktechlab-help" for a protocol? So a 
link to the context help for another item would look like 
"ktechlab-help://ec/resistor" ("ec/resistor" is the id for the Resistor 
component; this method would need a method for exposing ktechlab's internal 
IDs for components). To create a help page for a "Übertragungsfunktion", for 
example, you'd make a link to "ktechlab-help://transfer-function", and 
clicking on the link would bring you to a blank page that you could edit.

* External pages; Hmm...the trouble with links to external pages is that the 
link will end up dead if the location of the page changes, etc. Are the pages 
you plan on linking to quite permanent?

> * The arrows in my screenshot are really ugly ;) Could you make the spikes
>    thinner, maybe as an option in the item editor?
Good point. I've made the default arrow half-head angle 20 degrees, and made 
it configurable.

> * This may be really hard, but do you think you could provide an easy way
> to include nice formulas? Do you know the LaTeX plugin for kopete
> (kopetex)? maybe you can make use from it?
kopetex converts the latex code to an image before using it. It's not hard to 
do it as kopetex does it (which involves only a few lines of code), but for 
ktechlab to use latex in a similar way, it would have to add a dependency of 
a latex-to-image converter (which for the moment, I think is excessive...).

(The other option would be to cache the text formula after creation, but then 
this makes the font size, etc., used in the image different to the help text 
for most users, and also adds the issue of how (or if) to store the formula 
inside the context help for future editing).

>    Mozillas mathml could also be an option, I don't know if KDE support it.
Nope, it can't be used.

> * We should provide a draft for new descriptions in order to get a
> consistent look. This draft could be shown for not documented objects and
> keywords. So for example the keyword "Übertragungsfunktion"
> (transfer-function) in the screenshot is not documented yet. This draft
> should invite a user to document it and send it to the list.
But what would a draft look like? There doesn't seem to be much that you could 
put in a template - "External Links", etc? Good idea if needed, though.