Decent helpfiles and FAQ planned for 1.6.0 or later?

[chris]

And perhaps we can fully integrate the help in the new unified GUI for Celestia (Qt) that is going to be realised in the near future. I would very much prefer, if the help could be handled within Celestia and no external program would be needed. But that would have to evaluated by people that know Qt.

Qt4 does have a QtHelp module that makes it easy to integrate searchable online help files. The Qt help file generator takes a set of HTML documents and creates a compressed help collection, so we're taking the right approach by using HTML now.

--Chris

[Guckytos]

And perhaps we can fully integrate the help in the new unified GUI for Celestia (Qt) that is going to be realised in the near future. I would very much prefer, if the help could be handled within Celestia and no external program would be needed. But that would have to evaluated by people that know Qt.

Qt4 does have a QtHelp module that makes it easy to integrate searchable online help files. The Qt help file generator takes a set of HTML documents and creates a compressed help collection, so we're taking the right approach by using HTML now.

--Chris

That sounds really nice.

Now all we have to do is find out:

• WHAT we want to put in the help
• HOW it should be looking like
• WHO is going to do what
• WHEN it should be done
• ...
• and most important find out who is going to go nuts, while trying to organize it

Guckytos

[Guckytos]

I think that's about it. If you could include all those changes and update the FAQ with the latest version (see some posts above) then it should be finished.

Thanks!
Give me a couple of days, and i?ll have a final doc ready for review.

- rthorvald

Hi Runar,

how are things progressing?

Regards,

Guckytos

[Guckytos]

Hey guys and gals,

after this subject went a bit into hibernation in the winter, there are now news.

Runar has finished the new version of the HTML helpfiles. Well, okay at the moment it is only a blown up FAQ combined with the README and the controls.txt, but it will become the core of the future help.

Please help us by proofreading it.

Here is the link: http://www.celestialmatters.org/users/rthorvald/guide/

Best regards,

Guckytos

[selden]

R and Shift+R are listed.

However, R and shift+R are not used in 1.6.
The Texture Resolution commands have been moved to the Render menu.

[Chuft-Captain]

However, R and shift+R are not used in 1.6.

Have they been re-mapped to some other function?

[chris]

However, R and shift+R are not used in 1.6.

Have they been re-mapped to some other function?

No, these keys are not currently used.

--Chris

[Guckytos]

Hi everyone,

as I already tried to state on the dev list (file size of the packed file was still to big): I had finally time to polish up the new HTML help file that Runar and I were working on since last year and the work you could see in this thread.
It is not meant to be put into 1.6.0, as the release is too close, it's not really finished and translators (including me) would have to do a lot.

But now I need some feedback, of what you think about it. If it looks okay to be included perhaps already in 1.6.1...

Please give it a careful look over and report any things that you think could be done better (perhaps they will be taken into account ) or any errors that you find (these will be tackled for sure).

It is still a work in progress and not finished, as some input files are also still changing (README).

Especially the Keys section would need a good look from all sides.

Guide.rar

Best regards,

Guckytos

[selden]

Guckytos,

It's clear you put quite a lot of work into the rewrite. it looks quite good. Thanks, a lot!

However...

I think it would work better if you could eliminate all of the scripting and css, so that it only consists of one plain html file. There are at least two reasons for this.

1. On my computer, at least, Internet Explorer complains and refuses to run the scripting unless I do something special. I think this would be confusing to the novice, and would cause unnecessary anxiety.

2. The use of many support files will make it difficult to maintain, especially if you are not available to make the necessary corrections.

[ElChristou]

Selden, IE cannot open this file?
(I'm kind of astonish as you can find this kind of script and css in lots of web site out there!)

[selden]

IE refuses to open the file until the user has said that it's OK.

But how can the user know it's OK? For all he knows, the scripting will immediately trash his computer.
For this and other reasons, scripting needs to be avoided when it's not necessary.
Documentation just needs to be readable.

[jogad]

Hello

I like very much the presentation of this help and it would be a pity not to use its features.

There is no problem when we launch the help from the web here
http://www.celestialmatters.org/users/rthorvald/guide/

The problem is only when we try to do it from the local hard disk. This is because a stupid option of IE. The file is not more dangerous on your computer than on the web.
To have a correct behaviour we need to correct it like this.


Close and re-open IE and it is done!

Note: The line says something like "let execute active content t in the files of my computer"

[ElChristou]

...Documentation just needs to be readable.

Yep, you're probably right and your problem with Runar fancy and elegant work is really annoying. Nevertheless the problem of documentation "just" readable is that in general no one read it. Now, as we want Celestia more user friendly with new GUI, content, etc, this doc was perfect from this point of view. Clear, again elegant and really clever. Why clever? because there is quite a lot of content in it and despite this point the doc seems "light" (easy to read/easy to understand/easy to assimilate). IMHO it was a really good doc for a soft as complex as Celestia...
But, BTW, what's the idea here? online doc? Imbued in the next GUI? Or simply just like this (in a folder next to the app)?
If option one or two, perhaps your problem is not relevant? If option three, then yes I guess too much people are still using IE and so something should be done...

[chris]

But, BTW, what's the idea here? online doc? Imbued in the next GUI? Or simply just like this (in a folder next to the app)?
If option one or two, perhaps your problem is not relevant? If option three, then yes I guess too much people are still using IE and so something should be done...

How to distribute the documentation is yet to be determined. I guess my preference right now would be to distribute it with the application. Qt4 can compile a set of html documents into an indexed and searchable help file, which seems useful to me. I'm not sure how much of the formatting is preserved. On the other, online documentation can be much more easily updated, so I see the advantage there...

--Chris

[Guckytos]

...Documentation just needs to be readable.

Yep, you're probably right and your problem with Runar fancy and elegant work is really annoying. Nevertheless the problem of documentation "just" readable is that in general no one read it. Now, as we want Celestia more user friendly with new GUI, content, etc, this doc was perfect from this point of view. Clear, again elegant and really clever. Why clever? because there is quite a lot of content in it and despite this point the doc seems "light" (easy to read/easy to understand/easy to assimilate). IMHO it was a really good doc for a soft as complex as Celestia...
But, BTW, what's the idea here? online doc? Imbued in the next GUI? Or simply just like this (in a folder next to the app)?
If option one or two, perhaps your problem is not relevant? If option three, then yes I guess too much people are still using IE and so something should be done...

Yes, a very big thanks to Runar for designing the HTML template, I am very thankful that he did that. I am not very good at HTML, CSS and let alone JS. I think also as Christophe that it looks really good and is easy to navigate.
For this version I just adapted a few points (added a menu point and revamped the "Contributions").

The idea here (at least from my side) is to use it as an interim solution (to be included already in 1.6.1?) and have it called up, when you select "Help" within the help menu in Celestia. Calling up the standard webbrowser of the user and presenting the file most probably.

And it should also be a guide and cornerstone to a "real" help file in the unified GUI. But for that I would then very much prefer to use XML files as input files. Those are a lot easier to maintain.

I also have an idea about an issue that was just encountered with the README and its quotations of textures not being up to date and correct. Well, if you don't read every post in the forum and/or the dev list, it's easy to overlook something.

Why not make something like a database in Sourceforge, where everyone that is updating/putting textures, models, scripts ... in the official package is requested to enter a dataset before the content is put in the trunk?
Okay it would be a lot of work to do that for everything that is already in there, but it could be worth it. We would have a clear documentation and it would be easy to export it into a help file or where ever. And we could also see, how old a texture is and what was used to create it.

For textures I was thinking about a dataset like this:
Object; resolution (maximum); creator; source (with date); type 1 (normal, bump, emissive, ...); type 2 (LOK, fictional/interpreting); manipulation (colorizing with reference, ...); date of creation; special data (cooperation, rework, etc...)

Best regards,

Guckytos

[Guckytos]

But, BTW, what's the idea here? online doc? Imbued in the next GUI? Or simply just like this (in a folder next to the app)?
If option one or two, perhaps your problem is not relevant? If option three, then yes I guess too much people are still using IE and so something should be done...

How to distribute the documentation is yet to be determined. I guess my preference right now would be to distribute it with the application. Qt4 can compile a set of html documents into an indexed and searchable help file, which seems useful to me. I'm not sure how much of the formatting is preserved. On the other, online documentation can be much more easily updated, so I see the advantage there...

--Chris

Hi chris,

well, the formatting would have to be tried out then with Qt4. If we don't reach the same level as with Runars template, that's bad, but not a stopping point, I would say.
For online documentation, we have the WikiBook, that should be normally up to the latest informations.

But I really like to have at least a basic documentation of a software on my own PC without haveing to be always connected to the net to look up every damned command. I know that that is a dying out opinion, but I am old-fashinioned in that respect.

Best regards,

Guckytos

[Chuft-Captain]

But, BTW, what's the idea here? online doc? Imbued in the next GUI? Or simply just like this (in a folder next to the app)?
If option one or two, perhaps your problem is not relevant? If option three, then yes I guess too much people are still using IE and so something should be done...

How to distribute the documentation is yet to be determined. I guess my preference right now would be to distribute it with the application. Qt4 can compile a set of html documents into an indexed and searchable help file, which seems useful to me. I'm not sure how much of the formatting is preserved. On the other, online documentation can be much more easily updated, so I see the advantage there...

--Chris

I think there's a way to produce a single documentation file which is both able to be integrated and searchable within an application as well as readable online.
I think this is XML based. (and I think TheGIMP uses this technique, so might be able to use that as an example.)

CC

PS. I'm not sure how effective this is as to date I haven't actually used The Gimp Help.