Help Files in Celestia

[Evil Dr Ganymede]

Is the Celestia FAQ actually included in Celestia's help files? I notice that a lot of new subscribers here ask questions that have already been explained there - perhaps if it was included with the program (and accessible from within it) then this wouldn't happen so much. That'd probably be as useful as putting all the keyboard shortcuts in there... the version of Celestia (one of the later 1.3.1s) I have at least only has the controls in the help file and that's it. Which isn't, to be honest, particularly helpful in a lot of cases.

Is there any particular reason why a proper text help file hasn't been inlcuded in Celestia that is accessible from the Help menu there? Heck, even if the User Guide is included that'd probably cut down on a lot of questions.

(just for comparison, POVray (another open source project) has VERY extensive help files and documentation included in it)

[selden]

Oh Evil One,

There is no extensive Help file because nobody has taken the time to write one.

Are you volunteering?

[Evil Dr Ganymede]

It seems to me that nobody needs to write one...

Even just including the FAQ and the User Guide (in whatever state they exist at the time the program is released) would be more information than what is already included in the Celestia's help menu. It surely can't be that hard to do (even if clicking the relevant bit of the help menu just opens a local HTML copy of the FAQ or User Guide, that'd do the job).

I'm just suggesting this so that people have something to read right there in Celestia before they come here asking the same questions over and over.

[selden]

Oh Evil One,

Actually, I was seriously suggesting that you (or anyone else, for that matter) would be doing the Celestia community a great service if you would take the time to produce such a help document. Each of us has different priorities and a limited amount of time to spend on them. This is the kind of project where most of the work does not involve any coding changes to Celestia.

Since Celestia has to work on several different platforms, either plain text or HTML probably are the best format choices. Adding appropriate links in the various Celestia menu systems should be relatively easy, once such a document is available. As a separate file, it also would be relatively straight forward to translate it into other languages.

Implementing the equivalent help in all of the different system specific help systems would be a lot more work, although there probably are tools to make the translations easier than doing each one manually.

[Evil Dr Ganymede]

Well, it shouldn't be too hard to take the existing FAQ thread here and condense the threads to turn it into a single HTML webpage.

I don't have a lot of time right now to do it, but somone else might be able to...

[ANDREA]

Well, it shouldn't be too hard to take the existing FAQ thread here and condense the threads to turn it into a single HTML webpage. I don't have a lot of time right now to do it, but somone else might be able to...

Hello Selden and Evil One, I think you are speaking of two VERY different things:
Selden speaks of a TRUE Help file, with all the incredible number of information that is actually spread all over the Celestia links.
Evil One is speaking of a very simple "copy and paste" of the FAQs actually present in Celestia Forum, but given in simple .txt format and, I suppose, included in the next Celestia releases.
If I'm right, I can realize the Evil One's proposal, but I'm absolutely unable to realize Selden's, sorry.
But IMHO Selden has already made a lot of work, even if it's under HTML webpage and not .txt file.
I understand that many chapters need the images provided by Selden in his pages, but probably a .txt file with the addresses to those pages could be VERY useful.
Any proposal?
By

Andrea

[selden]

Andrea,

I was trying to suggest that someone could create either a text or html file, and that, as you say, a real help file would be a lot of work.

[Evil Dr Ganymede]

Yeah. Like I said, the main reason for my question/request is that the FAQ isn't actually there in the program for people to look at before they come here asking the same questions all the time (and not reading the FAQ first, sigh).

There's no guarantee that they'd read the FAQ that came with the program of course, but usually if people have a problem they check the help files first . Except at the moment the only thing in the help files are a list of controls, which don't really answer many of the questions people would have about how to actually do things.

So I'm just suggesting that the FAQ be added to the program to hopefully reduce that problem. I agree, a fullblown help file would be great, but it would be a pretty big endeavour, and given the rapid rate at which the program is evolving from one version to the next the goalposts would be shifting rather rapidly.

I think it would also be worth including the current User Guide with the program too (because that is a separate file anyway), either linked via the help menu or just there in the directory structure under "manuals" or something.

The good thing about including the FAQ and the User Guide is that it wouldn't be very difficult to include them, and it may answer a lot of questions for people straight away.

[don]

Is there any particular reason why a proper text help file hasn't been inlcuded in Celestia that is accessible from the Help menu there?

Actually, there are several reasons:

1) Celestia is not cross-platform. Rather, it is multi-OS. In other words, only the core code is cross-platform. Each and every Operating System and OS Interface (KDE, GTK, OS/X, Windows, etc.) has it's own directory full of source code. This makes the Celestia interface look different on each "platform", thus requiring the Help system to be written in such a manner as to cover ALL platforms that Celestia runs on. It also means the Help system must be coded into each and every individual interface available -- not just Windows.

2) The Windows interface code is mixed in with the core code, which means that the core code would need to be modified in order to integrate the Windows version of the Help system. However, Chris gets very nervous when someone else, besides himself, touches the core code. Since he is not interested in creating a Help system (boring work), it's not getting done.

3) In December of last year (2003), Chris all but demanded that all future documentation for Celestia be written in DocBook format, which happens to be used primarily on Linux systems.

Earlier this year, I downloaded over 300 MB of "DocBook" programs that were converted to supposedly run in Windows (what I use). I tried, in vain, to learn and understand DocBook, but found that most of the programs did not work properly in Windows and gave up in utter frustration.

So, I agree with you Dr. Evil ... screw Chris' "preference" for DocBook format documents, and go with simple HTML and "target=" statements, just to have SOMETHING! Something, regardless of the format, is certainly better than NOTHING.

[Evil Dr Ganymede]

Don - I don't see why any of those reasons are actually relevant here.

1) HTML or txt is cross-platform - it can be the same for all versions. If links are a problem for some reason, then we don't need to include them.

2) the core code doesn't need to be touched at all.

3) well, that's just silly IMO .


you're right though - something will definitely be better than nothing.

[don]

Reasons...

1) Means it is a difficult and complex task to create a "Help System" that will be useful for all of the different OSs/interfaces. Not an easy task for a casual user to accomplish. Also, HTML does not create an integrated "Help System", but rather, a Help web site, for either on or off-line usage. This is different than Microsoft's proprietary browser-based Help System.

2) If the "Help System" is to be integrated with the program, yes, the source code for every OS interface must be modified. If the Help System is to be stand-alone, then no, the source code does not need to be modified.

3) Agreed.

[chris]

2) The Windows interface code is mixed in with the core code, which means that the core code would need to be modified in order to integrate the Windows version of the Help system. However, Chris gets very nervous when someone else, besides himself, touches the core code. Since he is not interested in creating a Help system (boring work), it's not getting done.

The only part of the code that I get nervous about is the rendering. Adding a help system would in no way touch this. If someone wants to convert some documentation to Windows help format and modify the Celestia's Windows UI to accomodate it, I'd be very pleased indeed. I'd still prefer to have a common set of documentation in DocBook format from which other formats--including Windows help--could be derived. But, until that happens, an OS-specific solution is better than nothing. I'm busy rewriting much of the star code, so I have zero time to work on user documentation right now.

--Chris

[ANDREA]

Andrea, I was trying to suggest that someone could create either a text or html file, and that, as you say, a real help file would be a lot of work.

Well, I offered myself as volunteer, so here we are:

http://www.ara-frasso-sabino.org/CELESTIA%20USER%20FAQ%20Q0-Q24.doc

Selden, please check my "INDEX", it's the only think I've added, but I'm not an English speaking man, so... Feel free to make any correction or change you think useful.
Thank you.
I have it in .rtf too, and in .pdf, but with this I've not been able to maintain the internal hypertext links (i.e. from INDEX to the Qs).
Hope this is what requested by Evil One
Obviously if this file will be used, I will upgrade it, when needed.
By

Andrea

[Evil Dr Ganymede]

Yeah, something like that. I was figuring it could be linked to in the help menu. HTML might be a better format though to view it in.

[Adirondack]

Hm, so far so good...

But I can't understand why newbies and other users don't ask themselves: "Isn't there a documentation where I can find answers?"

And in fact, one can find documentations on almost every corner:

1. http://www.shatters.net/celestia/documentation.html
2. http://www.celestiamotherlode.net/catalog/documentation.html with a lot of helpful links
and even here in the forum:

http://www.shatters.net/forum/viewtopic.php?t=3481
http://www.shatters.net/forum/viewtopic.php?t=5783
http://www.shatters.net/forum/viewtopic.php?t=2291

The users just have to search, everything is easy to find.

What about with all the efforts of Frank G., Don G., Selden B., Bob H. and all the other documentation-writers?
They spent a lot of their time to create their documentations and nobody seems to read the manuals.

As far as I know, nobody is even able to say "Thank You" to Frank, Don, Selden and Bob. Shame on you.

Adirondack

[HB]

A while ago and more or less for my convinience I've made some kind of Celestia Library in HTML format for local use only. This consist out of a main frame/page from where you can go to a collection of manuals or books such as The User manual, Don's Script guide, the sourcecode reference, Guilpains stc,ssc manual, Lua scriptguide's and reference manual, AstronomyAnswers from the astronomy dept of the university of Utrecht,The nine planets, and Seldens page's. (All pages are located on the harddisc)

Some these html-documents has been modified for this purpose and the total has become rather huge. For common use not all of these manuals are needed. Manuals like the sourcecode reference and one of the lua manuals could certainly be skipped and perhaps other less relevant documents or pages as well.

Anyway for each and every manual or document a table of contents has been created for a quick access to the information your looking for.
The modification to the original pages has been kept to a minimum or without any change at all. In this way it's at least for me quite easy to update this libraries with newer versions of manuals.

Right now one click brings me to this library( later from within Celestia)

If it is in someones interest I'm glad to give in this way some contribution to the Celestia-users.
There's only one problem: how to get this published?? How to upload it??

Hans.

[selden]

Hans,

I'd suggest making it available on http://celestiamotherlode.net/

See http://www.celestiamotherlode.net/faq.html for more information.

[Bob Hegwood]

As far as I know, nobody is even able to say "Thank You" to Frank, Don, Selden and Bob. Shame on you.

Adirondack

Ulrich,

I suppose you've received just loads of thank you's for YOUR German-speaking
Guides too. Not a problem for me. I wrote my guides for ME. After
each was finished, I finally understood something of the processes I was
trying to explain. This is a great way to learn a topic, yes?

If someone else can benefit from a particular guide, that's great. Really
though, mine are written to explian things to myself. You *know* how
much my Brain needs the excercise.

By the way, has Christian (Guckytos) contacted you for your picture?
The STC Guide he has written offers an *excellent* explanation for the
layout of the Star Catalog files.

Take care, Bob

[Evil Dr Ganymede]

Hm, so far so good...

But I can't understand why newbies and other users don't ask themselves: "Isn't there a documentation where I can find answers?"

And in fact, one can find documentations on almost every corner:

*snip*

They spent a lot of their time to create their documentations and nobody seems to read the manuals.

As far as I know, nobody is even able to say "Thank You" to Frank, Don, Selden and Bob. Shame on you.

Adirondack

You answered your own question. The documentation is indeed on every corner... except where you need it the most, which is actually in the program. Most new subscribers to the forums probably don't even realise that there's a FAQ or documentation here. And frankly, IMO you shouldn't have to get the sort of information that is contained in that documentation separately from the program.

It's not a question of anyone being ungrateful for the work that's been done, it's more a case of actually putting that work in a place where it's actually going to be noticed and read and used!

[Adirondack]

Bob,

I suppose you've received just loads of thank you's for YOUR German-speaking
Guides too. icon_wink.gif

Actually a few users did and do say "Thank you". But the most of them didn't.
Not a problem for me, but it's just a question of decency.
It seems that a complaint is easier to say, but an appreciation.

By the way, has Christian (Guckytos) contacted you for your picture?
The STC Guide he has written offers an *excellent* explanation for the
layout of the Star Catalog files.

Yes. I've read his guide and it's really brilliant.

Adirondack