Celestia Forums

Howdy All,

Is there somewhere that I can find a compiled Windows package (Zip?) for the latest pre-release?

I am attempting to put together a Scripting manual (text format) and would like it to be as up-to-date as I can make it, with examples tested against the latest version.

Thank you!

-Don

Please read the "preliminary Users' FAQ" at the top of the Users Forum:
Q3/A3 and Q6/A6
Not to mention Q15/A15.

Gee Seldon, you forgot to include the Devil emoticon in your reply

You didn't need to be rude, when a simple URL would have sufficed. Seems it would have been QUICKER too, instead of typing all the text that you did. Your message sure was a great way to "welcome" me and thank me for wanting to helping out .

Regarding Q6/A6: I already have the limited user docs available, and did not ask for this.

Regarding Q15/Q15: I already have the limited Scripting docs available, and did not ask for this.

In case you didn't read my entire message, I am attempting to HELP the Celestia project, for FREE (like everyone else here) by writing a Scripting Guide for it, so please don't come down on me.

I read the "preliminary Users' FAQ" when I first downloaded Celestia several weeks ago, but obviously didn't remember it telling me where I could find pre-release versions. I am terribly sorry that I asked before looking. My mind has been full to overflowing the past few days, from reading through all the Celestia forums, other people's Celestia web pages, as well as all the information on the SourceForge "backup CVS server" (been in "backup" mode ever since I first logged onto it several days ago) for Celestia ... trying to find ANYWHERE where ALL, or even a few, of the Celestia script commands and parameters are documented / described (what they are, what they do, what their expected value ranges are, etc.). However, all I have found is mostly UNCOMMENTED scripting-related source code (command.cpp, body.cpp, cmdparser.cpp, etc.) and a short HTML document from another user listing a few of the script commands. Oh, and a re-printed excerpt listing the commands from one of the source code files.

I can't believe any developer, in their right mind, would spend days upon days writing complex, object-oriented, programming code and then not comment a single line of it, which would allow someone else to document all their hard work in a user-readable fashion! I would have been fired, from any of my probono OR paid jobs, if I had programmed without commenting what the code was supposed to do. Yes, I was an analyst/programmer for 20+ years, up to mid 1995 (no Object-Oriented stuff though).

The lack of a comprehensive scripting guide is exactly WHY I decided to try and HELP out. But, if my FREE help is not going to be appreciated, or if my questions (and there will be MANY) are going to go UNanswered, like so many others in the forums, then maybe I should just move on and do something a little more productive and rewarding with my time?

I LOVE Celestia and would LIKE to help make it a better product by writing a scripting guide, BUT I am going to need some cooperative assistance from the developers and other experts in it's use and code.

Should I continue on this path, or take a hike?

-Don

Anonymous wrote:Gee Seldon, you forgot to include the Devil emoticon in your reply

You didn't need to be rude, when a simple URL would have sufficed. Seems it would have been QUICKER too, instead of typing all the text that you did. Your message sure was a great way to "welcome" me and thank me for wanting to helping out .

Don, I'm sorry: I really wasn't trying to be rude. I was at work and didn't have time to write much. Also, I wanted to make sure you were aware that some of the information already was available. I know how frustrating it can be to launch off into a project and half-way through find out that someone else had already done most of the work.

Since you didn't mention that you knew about the FAQ, I had to assume that you didn't. Too many people keep asking questions that are answered there. Personally, I find that putting some of my own effort into finding the information helps me to remember them more than if someone just says "here it is".

Regarding Q6/A6: I already have the limited user docs available, and did not ask for this.

Regarding Q15/Q15: I already have the limited Scripting docs available, and did not ask for this.

My experience has often been that when people don't mention pre-existing documentation, it's because they haven't read it or don't realize it exists.

In case you didn't read my entire message, I am attempting to HELP the Celestia project, for FREE (like everyone else here) by writing a Scripting Guide for it, so please don't come down on me.

I think a scripting guide is a great idea.
Just bear in mind that there are two scripting languages and that the original .CEL language is being "deprecated", although it won't go away. All future scripting support in the source code will be for Lua, not for .CEL.

I read the "preliminary Users' FAQ" when I first downloaded Celestia several weeks ago, but obviously didn't remember it telling me where I could find pre-release versions. I am terribly sorry that I asked before looking. My mind has been full to overflowing the past few days, from reading through all the Celestia forums, other people's Celestia web pages, as well as all the information on the SourceForge "backup CVS server" (been in "backup" mode ever since I first logged onto it several days ago) for Celestia ... trying to find ANYWHERE where ALL, or even a few, of the Celestia script commands and parameters are documented / described (what they are, what they do, what their expected value ranges are, etc.). However, all I have found is mostly UNCOMMENTED scripting-related source code (command.cpp, body.cpp, cmdparser.cpp, etc.) and a short HTML document from another user listing a few of the script commands. Oh, and a re-printed excerpt listing the commands from one of the source code files.

Hmmm. I don't recognize what I wrote among those descriptions, unless you're trying to be sarcastic. I spent a lot of time reformatting the commands and listing all their arguments.

Be sure to contact Frank Gregorio, the author of "User's Guide volume 1". He's been planning to write a scripting guide (vol 3 of the set) and may have done some initial work on it already.

I can't believe any developer, in their right mind, would spend days upon days writing complex, object-oriented, programming code and then not comment a single line of it, which would allow someone else to document all their hard work in a user-readable fashion! I would have been fired, from any of my probono OR paid jobs, if I had programmed without commenting what the code was supposed to do. Yes, I was an analyst/programmer for 20+ years, up to mid 1995 (no Object-Oriented stuff though).

(Un) fortunately, the authors of Celestia are concentrating on providing features, not documentation. They all know the code by heart. Usually the intent of OO code is rather more obvious than the older procedural languages. Except when it's "OO" code that's been written by a Fortran programmer.

The lack of a comprehensive scripting guide is exactly WHY I decided to try and HELP out. But, if my FREE help is not going to be appreciated, or if my questions (and there will be MANY) are going to go UNanswered, like so many others in the forums, then maybe I should just move on and do something a little more productive and rewarding with my time?

Many questions go unanswered because there aren't enough people who know the answers. Most of those who do are busy doing other things. To be blunt, not everyone even has my patience.

I LOVE Celestia and would LIKE to help make it a better product by writing a scripting guide, BUT I am going to need some cooperative assistance from the developers and other experts in it's use and code.

Just be aware that you aren't going to get a lot of direct help. There are only a very few active developers, and they'd rather be spending what little free time they have available extending the program's functionality. They all have quite demanding full-time jobs. And I think many of us would prefer they spend their time that way.

Should I continue on this path, or take a hike?

I think a usable scripting guide would be great.

However, I do think you should take the time to register on the forum. Also, make sure your browser accepts the Forum's cookies so you don't have to keep logging in.

Anonymous wrote:... as well as all the information on the SourceForge "backup CVS server" (been in "backup" mode ever since I first logged onto it several days ago) for Celestia ...

It'll be that way at least until late in August when they get their hardware upgraded. As an attempt to improve response times, only registered developers have access to the primary server.

See the entry for July 12th on http://sourceforge.net/docman/display_doc.php?docid=2352&group_id=1

Howdy Selden,

Thanks for your reply.

Sorry about the "Guest" sign-in (sigh). I *am* a registered member of the forums. Guess it's just not my day today. The phone lines (thus our DSL connection) were out of commission for about 4 hours today. Someone cut the main line. I guess turning off the DSL modem and disconnecting our internal network from the router must have screwed something up in the forum code because I never turned the PC off. When I came back, I didn't realize I was not automatically logged in until I saw the posted message (sigh). Then, I also learned that there doesn't seem to be any way to edit a post, like on other forum systems. Oh well. Like I said, just not my day.

I recall reading several messages regarding Lua, and even spent a little time at their web site. However, it did not "click", or I failed to read, that it was going to REPLACE .CEL in Celestia.

With this new knowledge, my first question would be: "Will there be any further development to the .CEL side of the code?" In other words, any more enhancements to .CEL? If not, then I'd hate to waste all the time and effort into creating a Scripting Guide for .CEL in it's current condition ... it's GREAT to have it, but it's kinda weak ... especially when it's on the way out the door.

My second question would be: "When (version or date) is Lua planned to be included as the new scripting language?


> Hmmm. I don't recognize what I wrote among those descriptions ...

Ahhhhh, I now see that you are the creator of "Celestia notes.htm", which includes "4.0: Script Commands. Defined in / celestia / celestia / src / celengine / cmdparser.cpp". I had not printed out the entire document, but only the Script section for reference, which does not include your name. No, I was not being sarcastic in describing the list of documents I found. To me, the 4.0 section of the document is just as easy to read as the source code itself, since I have programming knowledge, which is why I referred to it as "a re-printed excerpt listing the commands from one of the source code files."

Sorry if that offended you in any way. I had hoped a re-worked script command listing would contain some explanation as to *what* the non-obvious commands do; along with what the variables are (as if 'up' is a descriptive parameter name?!); what the variables actually set; what the valid input ranges are; etc., etc. That's why I referred to it the way I did.

I don't want to argue with anyone about poor coding practices, because someone else (Chris) is in charge of this project and not me. But, I would hope that someone along the way would ask the current programmers to document the code they are so fervishly working on. Why? Because tomorrow they won't remember WHY they wrote routine "Z" the way they did, instead of writing it another way. In addition, when persons A thru K are gone from "the programming team", and persons L thru Q take their place, the new programmers won't have a clue what the code is supposed to be doing, or why it was written in a particular way, until they learn the entire system! Based on my personal experience, no code comments WILL deter additional programmers from joining the team.

To me, "being too busy writing code" is absolutely no excuse for not documenting what you just wrote into in-line comments. Commenting is *part of* writing good code. IMHO, it's just a cheap excuse to be lazy. How can I possibly write any of this? I've "been there, done that", and am very glad I got reformed as early as I did in my programming career, for my own sanity, like when it came time to maintain that 30,000 line, 60-module, custom database system I finished several years ago (smile)!


> Be sure to contact Frank Gregorio, the author of "User's Guide volume 1".

Thanks for the tip. Yes, I have his guide and should write to him to find out where he's at in his work on "Part 3". It's been a while since I've done anything like this where lots of other folks are involved.


> Except when it's "OO" code that's been written by a Fortran programmer.

(laughing) Or by an old BASIC, COBOL, and database programmer (me), which is why I gave up even trying to learn / code in C and C++ (frown). Too much like ASM (assembly language) for me.


> To be blunt, not everyone even has my patience.

Ouch. Guess I'd better make sure to "chill-out" before I login to the Celestia Developer forum, and just try to have some fun, looking past the words and/or tone. Thanks for the warning!

Thanks also for the URL to the Site Status Page on SourceForge. It's a great service they offer, and it looks like they are going through some serious growing pains. Good to know they are working it all out.

Cheers for now...

-Don

don wrote:I don't want to argue with anyone about poor coding practices, because someone else (Chris) is in charge of this project and not me. But, I would hope that someone along the way would ask the current programmers to document the code they are so fervishly working on. Why? Because tomorrow they won't remember WHY they wrote routine "Z" the way they did, instead of writing it another way. In addition, when persons A thru K are gone from "the programming team", and persons L thru Q take their place, the new programmers won't have a clue what the code is supposed to be doing, or why it was written in a particular way, until they learn the entire system! Based on my personal experience, no code comments WILL deter additional programmers from joining the team.

Being the last active programmer to have joined the project, maybe I can comment a bit on this.

Personnaly I most often don't find comments particularly helpful, if I want to know what a piece of code does I just read it. What I would have found a lot more helpful when I joined is a class map explaining at high level the role and relationships between them, but even that was relatively easy to work out by myself.

I think what needs to be documented or commented in the code and is somewhat lacking in Celestia are design decisions. Why don't we have a parent 'Object' class, why use instead the Selection class, for example. The kind of thing that a new programmer will find awkward or illogical but are in fact sound.

Maybe what we should work toward is using a documentation tool like Doxygen, that would encourage better or more systematic comments and also help define the interfaces between the objects.

Duhhhh, I can see that my second question (When will Lua be included) is also answered in the FAQ, yet again ... 1.3.1 pre3.

My brain must have checked itself out at some point on Sunday (sigh). Too much reading of too many things.

Not sure that I'm up to learning yet another programming language either, especially just to automate a few keystrokes in Celestia (frown).

don wrote:I don't want to argue with anyone about poor coding practices, because someone else (Chris) is in charge of this project and not me. But, I would hope that someone along the way would ask the current programmers to document the code they are so fervishly working on. Why? Because tomorrow they won't remember WHY they wrote routine "Z" the way they did, instead of writing it another way. In addition, when persons A thru K are gone from "the programming team", and persons L thru Q take their place, the new programmers won't have a clue what the code is supposed to be doing, or why it was written in a particular way, until they learn the entire system! Based on my personal experience, no code comments WILL deter additional programmers from joining the team.

To me, "being too busy writing code" is absolutely no excuse for not documenting what you just wrote into in-line comments. Commenting is *part of* writing good code. IMHO, it's just a cheap excuse to be lazy. How can I possibly write any of this? I've "been there, done that", and am very glad I got reformed as early as I did in my programming career, for my own sanity, like when it came time to maintain that 30,000 line, 60-module, custom database system I finished several years ago (smile)!

I comment the code where I think that it needs it . . . Take a look at render.cpp or octree.cpp for some examples. I'm certainly not lazy or anti-comment . . . But, comments do have a tendency to get out of sync with the actual code. My philosophy is to program literately, using a clear style with descriptive variable names, and to provide comments where I feel additional explanation is required.

I concur with Christophe's opinions that what is mosted needed are a class map giving a high-level overview of how Celestia operates and an explanation of some of the major design decisions. I'll have a look at Doxygen . . .

--Chris

chris wrote:I comment the code where I think that it needs it . . . Take a look at render.cpp or octree.cpp for some examples. I'm certainly not lazy or anti-comment . . . But, comments do have a tendency to get out of sync with the actual code. My philosophy is to program literately, using a clear style with descriptive variable names, and to provide comments where I feel additional explanation is required.

I concur with Christophe's opinions that what is mosted needed are a class map giving a high-level overview of how Celestia operates and an explanation of some of the major design decisions. I'll have a look at Doxygen . . .

--Chris

Howdy Chris,

First off, thank you for creating such a FUN program.

Since I retained very little knowledge about what I managed to learn in OO programming many years ago, I am coming into this project as a possible end-user document writer, with ZERO knowledge as to how Celestia is written. Therefore, I have only the source code comments to obtain the necessary information from, in modules such as cmdparser.cpp and command.cpp, which in fact use some meaningless variable names and include few to no comments describing what the functions are supposed to do, what the variable names mean, what the valid range of input values are, etc.

Now, if the source code I must extract information from has no comments in it, then I can't write comprehensive user docs from it, unless I too was an OO programmer, study the code, etc. So, my only recourse as a writer would be to bother you and all the other developers with a thousand questions.

Two brief examples, using a single command (goto):

1) The goto command uses a variable named "up". I don't have a clue as to what this variable is for, except that it has something to do with positioning because it's a vector. I would have to be on the programming team to know what this is. A variable named "up" is not descriptive (to me), unless it is contained within a routine that moves something up, down, left, right, etc.

2) Goto also uses a variable named "upframe", and only because of Selden's HTML document, do I know that it is the Coordinate System. Sorry, but the name "upframe", to me, is not a descriptive name meaning "Coordinate System". Maybe to a professional Astronomer?

It is not my intention to "put down" you or any of the programmers. I am merely trying to point out how limited to no comments is limiting the continued acceptance / maintenance / growth of Celestia as an end-user product, since there is limited documentation for it, and limited means by which a non-programmer can help out -- at least in the scripting department.

Cheers,

-Don

Don:

Just to answer your question, I have not begun writing Part 3 of the manual, which was intended to deal with scripting. I am currently updating Part 1 to reflect additions in version 1.3.1, and am still working on Part 2 of the Users Guide, which will deal with the world of Add-ons. Selden has already done some writeup on that which can be found on his site. I have not completed it yet due to a whole bunch of other activities, both related to Celestia and tyo ther things.

I'd be delighted if you tackle a Scripting manual. Please just remember that over 1 million people have downloaded Celestia and over 600 are members of the forum. They range from complete novices to skilled programmers. The tone and level of your scripting guide should assume that the reader has never attempted to write a script, has no idea what a script does and needs hand-holding in order to learn how to do it. It makes for a bit more word length, but is much appreciated by the folks who want to learn without having to bust their ass trying to understand a manual which presumes too much prior knowledge.

Looking forward to your draft. Feel free to send it to me if you'd like me to proof it for you.

Frank Gregorio

Hi Frank,

Thank you for your offer to proof the guide.

Yes, I have already begun the .CEL Scripting Guide and it is being written with beginning scripters in mind. However, it also contains an index of commands (alpha and by type) along with a full description of each command and it's parameters, making it useful to experienced users as well.

Currently, it's just a plain-text 56 KB file and has more work to be done on it. Some of the commands and parameters have been a challenge to figure out (for a non-astronomer) but thankfully, several folks are helping out as I move along and ask questions.

I love your Part 1 manual and am looking forward to Part 2!

Cheers for now,