Celestia Users Guide Part 1 is complete - examine here

[fsgregs]

Hi folks:

OK, the first comprehensive Celestia User's Guide, Part 1, is complete. It has taken quite a while to draft and incorporates all of the features of Celestia 1.3.0.

The Guide is designed to teach anyone using Celestia how to use the program and operate all of the controls, mouse movements and keystrokes. For the beginner, it is ideal. For the intermediate Celestia user, it may help you to understand some of the lesser known keystrokes and commands. For the experienced Celestia programmer and advanced user, it will be a complete, easy to understand reference that you may use or skip as you wish.

PLEASE NOTE: I have placed the Guide on my website for peer review and comment by forum members. The site is NOT the official repository of the Guide. My website has very limited bandwidth. Once it appears that it meets with your collective approval, Chris will post it on the Celestia website as a formal link for everyone to download. Hopefully, that will occur within a week or so.

The Guide is written in MS Word 2002 format (.doc). It has some tight formatting for photos. If anyone wants to tackle converting it to HTML or pdf or any other web friendly format without losing the formatting, please do so. Alternatively, Microsoft has a free download called Word Viewer that allows people who do not have Word, to view the document.

The Celestia User's Guide Part 1 is here:
http://www.fsgregs.org/celestia

Enjoy, Feel free to post comments here, or send them to me via private post.

Frank G

[Dave007]

HTML conversion done....tweaking the formatting now...should be done in about 30mins.

[jim]

Hi Frank,

first you did a great job. I can imagine that it's somethimes very hard to write this user guide.
With the following points i want help you to improve the some tings of the user guide.

Set Program Options (Render menu):
- The key shortcut should be added to the explained render features.

e.g.
Atmosphere
( strg + a )

Clouds
( i )

Track Selection:
-a good examplefor track and sync would be a moon eclipse viewing from a fix point on earth

Select Objects by Keystroke:
- h select always our sun. This should be added.

Saving Images and Locations
- Split this part into 3 sub headlines because is important and someone will search this in the Table of Contents.
1.Capiture image ( F10)
2.Capture Movie ( Shift + F10 )
3.Save a particular location

To save a graphic file (in .jpg or .png format), simply set up the screen as you want it, pull down the File Menu and select Capture Image. A menu will appear. Choose the folder you wish to put the file into, type a name for it; decide if it is to be saved as a jpg or png file and click SAVE. JPG files are common graphic files that are most useful for viewing in a computer running typical application software such as word processing or slideshows. PNG files are graphic files that are designed for viewing best on the Internet. If you wish to add your image to a webpage or E-mail it to a friend, save it in png format. Otherwise, use jpg format.

Something is wrong here. Let me try to to correct them.

To save a graphic file (in .jpg or .png format), simply set up the screen as you want it, pause Celestia with the space key. Now pull down the File Menu and select Capture Image. Choose the folder you wish to put the file into, type a name for it; decide if it is to be saved as a jpg or png file and click SAVE. Both graphic file type are very commen and can be opend by the most application software such as word processing or slideshows. The JPG files are very small but the compression causes a little quality loss. Yet the JPG format is most times the best choise especially if you use the image for the web or a E-mail to a friend. PNG files are also compressed files but without quality loss and larger on disk. Use this format if high quality is required.

(Translate my words into a good English!)
- The pause during the snap shot prevents from an unintentional "motion" effect.

Now the part 2 of user guide includes some difficult topics. I'm not able to help in writeing some parts (-> my enlish) but i would help you with some topics.

Ask me:
- all things about textures (DDS, normal maps, image editing)
- some things about 3DS models
I made already some posts about this thopics.

Bye Jens

[Dave007]

Well, 30mins was an undershot! I had to make a LOT of tables to preserve the formatting...but it's a pretty decent replica of the original.

I have the page up for review, but when it's finalized (everyone agrees on the authors' presentation) I would appreciate someone moving it to their server

You can preview the alpha here. WARNING: large page! This page may not stay up more than a day or two, it's over 2megs of bandwidth everytime someone loads the page, and I have a 500meg transfer limit. I am temporarily using GIFs b/c I forgot to tell Frontpage to use JPGs (colors look choppy on GIFs). I'll correct that soon.

I was unable to open the .doc file correctly with word, so I had to use wordpad. A hyperlink address was lost in the translation, and if anyone can provide it for me that would be great (the mars link). I also lost some formatting info, and had to use my best guess, let me know what to adjust.

Of course, the images can be compressed down, and I can be more robust with the HTML, but my aim was keep to the formatting.

Suggestions, comments, or flames are welcome via private or public post.

*update*
jpg conversion has improved image quality and reduced page size from 2.9meg to 564k

[t00fri]

Frank:

let me just mention here some superficial issues that struck my eye.

1) With Chris Laurel being a /coauthor/ of the manual , the "feature" story about him sounds to me like somewhat indecent "self-praising" style:

".. and creation of Mr. Chris Laurel, a gifted Seattle, WA computer programmer who in 2001, decided to write a free software program to be made available to everyone on the internet that would place you in control of a virtual reality world of the solar system. His vision and dedication gave birth
to a program that is unlike any other planetarium program in existence. "

The manual is much more Frank's work then mine, so I think that my role is more accurately described as contributor rather than coauthor. In any case, I'd feel more comfortable if that paragraph was omitted; just quietly credit me as the original author of Celestia and leave it at that.

--Chris

[fsgregs]

Hi folks:

I expect there will be several comments from the forum in response to the Guide in the next few days. Some will be minor, a few may require an entirely new paragraph to be added. Consequently, I suggest that folks who are working to convert the Guide to HTML or pdf, wait a bit to do so. If we add a new paragraph or two, all of the photos behind that addition will move and would only have to be repositioned in the HTML conversion anyway.

Jim and Fridger, thanks for your comments. I will make some changes in response to them.

With respect to the praise for Chris, I wrote it and insisted to Chris that we keep it in. After all, it was his initial vision that put us all here in the first place and some complementing in the document is well-deserved. However, to make it sound a bit less self-serving, I'll change Chris's input to "Edited by", since that has been his primary role in the Guide.

Fridger, you're right about Linux. I know absolutley nothing about Linux, what it can do, what it can't or any of its command menus or features. The same holds true for the MAC and OSX. I have to rely on Chris or you or others to insert any paragraphs about it that are needed to either correct or add to the Guide. If you could type what you think would be OK changes or paragraphs for your points 2 and 3 and e-mail them to me, I will insert them.

Also please note that the Guide was written in MS Word 2002. I have been told that most of its documents can also be opened and read by Word 6.0 and earlier, but it is possible Word 97 or Word 95 might not be able to read the Guide. If so, e-mail me and I'll send you the file in Word 6.0 format.

Thanks

Frank

[Guest]

Please emial me a Word 6.0 format .DOC, I am running Word2002, but this particular file crashes it everytime. I will hold off on updating the HTML version, and I'd like to mention now that I've imported and adjusted it into Frontpage, future editing is a snap.

If I have to take that page offline and someone wants to look at it, let me know and I'll bring it back up for a few mins.

[fsgregs]

OK, this kinda sucks! I have tried to convert my Word 2002 document to a Word 6.0 document for those folks who can't read 2002, and my computer says I don't have enough memory. I have 512 meg of total RAM and have at least 310 meg free, so the Word converter is going bananas!! I don't know why or what to do about it. I tried converting it to RTF format and it worked, but the file size was 82 MB. I suspect it did something weird with the graphics.

Once the document is finalized, we will figure out ways to post it in MS Word 2002, Word 6.0, HTML and maybe pdf, and any other format anyone wants.

Sorry



Frank

[t00fri]

Hi folks:

With respect to the praise for Chris, I wrote it and insisted to Chris that we keep it in. After all, it was his initial vision that put us all here in the first place and some complementing in the document is well-deserved. However, to make it sound a bit less self-serving, I'll change Chris's input to "Edited by", since that has been his primary role in the Guide.

I think you got my point: no intention to reduce Chris' merits, but as soon as he functions as an author this style is no good;-).

So I also would have proposed to let him act as an editor with you being the main writer. Then there does not appear to be a formal problem.

Fridger, you're right about Linux. I know absolutley nothing about Linux, what it can do, what it can't or any of its command menus or features. The same holds true for the MAC and OSX. I have to rely on Chris or you or others to insert any paragraphs about it that are needed to either correct or add to the Guide. If you could type what you think would be OK changes or paragraphs for your points 2 and 3 and e-mail them to me, I will insert them.

Sorry, but this will have to be done by someone else.

Bye Fridger

[Neeewbie]

I think this part is great:
"Here is just a taste of what you will be able to encounter: [...]"
But could you include the cel: links for (at least) a few of them?
That would be nice for newbies

[Neeeewbie]

Great! I finally understand how to use the track mode (before that i didnt know i had to press Esc to see this beautiful motion...)
"For example, if you are centered on Earth, release your hold on it with the Esc key and then hit the Track Selection command, Earth will begin to recede from you at the speed it actually travels in space (about 47,100 mph, or 78,500 km/hr), but your view will swing to track it."

[gaselli]

I can make it a PDF :)

A ~6Megs preview can be found at

http://www.kaisla.org/SUPPORT/celestia/

[fsgregs]

Dear Gaselli:

Your pdf file is beautiful. Formatting looks excellent.

Please remember that there will be some changes to the document before final print. For example, in reply to Selden's comments in an e-mail to me, I have increased the font size from Times New Roman 10 pt to Times New Roman 11 pt. It does make it easier to read, particularly when printed. This of course, boosts the document length an extra 4 pages and rearranges photos on different pages. There are also some additional comments, sentences and paragraphs being added that will change positional formatting.

I suspect the "final" document will be ready to publish in a few days. If you want to comment on the draft, please do so soon.

I will post the "final" draft on my website in MS Word 2002 format and let you all know. You can then download it and convert it to pdf and html. When Chris comes back from vacation (in a few days), we will get the document posted on the main Celestia website in at least 3 forms; .DOC, .PDF and .HTML, plus any other forms that appear needed.

Keep the comments coming.

Frank



Thanks

Frank G

[Paolo]

Hi fsgregs

First of all I want to express my congratulations for your very nice work. When I met Celestia for the first time I felt very strong the absence of a complete user manual. I'm waitin for the next chapters.
Thank you very much for you hard work .

I have a lot of experience in writing user manuals. Actually a part of my job consists in supervising the production of user manuals for the products of the company where I work. We use Word 2000 and Acrobat 4 so I know some tricks on how to use MS Word at the best and I can give you some suggestions.

First of all Word 2000-2002 uses an automatical internal compression system for included images. For example the included BMP images are automatically converted to a JPG-similar format when the document is saved. So this is one of the explanation of why when you downgrade the document format to previous Word versions or to RTF the file size literally explodes.

I suggest to enlarge the image size. Actually some of them are a little bit too small.

Some images seem to be innatural, seem to be stretched horizontally. Some planets looks oval. e.g. Figure 13, 14, 18, 19.

Placing the images is more simple if the images are set "aligned with the text". So you haven't to provide additional spaces and paragraphs.

Usually legends are placed at right-bottom of the images and numbering should be set automatic.

I think that some images of UI for various linux and mac-OS versions should be included.

To improve fast impagination I suggest the extensive use of styles.

All the manual documents need a structure that can allow cross references and automatic index building. So my suggestion is to use numbered formats for titles. The right balance for title numbering deep is to remain under 3 levels.

The character size is too small to allow fast reading. The "Times New Roman" font actually is out of fashion and more readable fonts are favorite (look at this forum for example ). I think that you should talk with Chris about the whole Celestia project graphical style: website, forum, user manual and so on.

Setting 2 or 3 points as spacing between paragraphs improves readability.
Personally I prefer justified paragraphs if possible, this gives a more professional aspect to the document. Obviously for HTML version it is impossible.

Notes, comments, suggestions and important advices should be identified more easily if some small images and different styles are used .

To convert the document in pdf format and reach a good compromise on the file size it is absolutely necessary to work on the images size. Some PDF converters like the original Adobe Acrobat allow a multilevel resampling setting to control the relation between quality for included images and size of the document. My experience suggests that only making some practical test it is possible to find the correct compromise.

If you give me the permission I can work a little on the document and improve the impagination .

Bye

[Dave007]

...Personally I prefer justified paragraphs if possible...Obviously for HTML version it is impossible.

HTML using justified text --> http://www.freewebs.com/personal1024/Ce ... eFinal.htm

[fsgregs]

Hi everyone.
I am delighted to have all of you folks help me get this ready for final publication. I have made some revisions to the document in response to comments and will be sending a new draft to my website tonight. In it, I have now even-justified the text as you suggested. My website host friend may or may not get it posted tonight. It is named "Users Guide Final-2". Watch my website at http://www.fsgregs.org/celestia until the revised document appears and the older version is removed.

I am certainly open to an alternative font for the text. If Times New Roman is not the best for viewing on the web or view screen, suggest another font.

With respect to the size of the photos, I have made a compromise between size of pictures and size of document. It is already 28 pages long. If I boost the photo size more, forcing some of them to scroll to new pages, it could be 35 pages long or more. Bigger photos may or may not be easier or more difficult??? to convert to pdf or html (anyone know??). If you think document size doesn't matter, I can always make the photos bigger. Please give me your thoughts.

Regarding photo positioning, I have personally not liked to imbed graphics in the text. It always seems to screw me up when I edit the text and the photos jump all over the place trying to reposition themselves. However, it does reduce whitespace. I simply am running out of time to try this out. Paolo, if you want to take the revised version from my website tomorrow, reposition/imbed the photos and their figure references, that would be wonderful. Please do so and e-mail me back your version. Likewise, I do not use MS Word enough to get comfortable with heading numbers, cross-referencing, etc. If possible Paolo, go ahead and add heading numbers or anything else to the "structure' you feel valid, and include it in the version you send back to me.

One comment asked if cel://URL links could be added to the photos. The answer is yes, but not this time around. I wrote the document over a month ago (yes, its been undergoing lots of edits prior to this posting) and when the photos were first inserted, cel://URL was not ready. Now, it is but I simply can't go back and reposition Celestia for all those photos just to get a cel:// URL link. When the next version of the Manual comes out (probably in a few months), we will include them.



Frank

[selden]

Frank,

Translating Word DOC files into PDF is "trivial". The full version of Adobe Acrobat adds a menu to Word. (or maybe its one of the freebee download addons for Acrobat.) One of the new menu itemsi translates the currently open Word document directly into a PDF file which is half the size of the original Word DOC file. All pictures are included. The visual appearance of the .PDF document is *identical* to the Word document.

The picture sizes seem adequate to me. Hopefully the person reading the manual will have access to Celetia and can reproduce them directly. I agree that eventually having Cel://URLs for each of them would be appropriate.

[Dave007]

Gaselli,
Your PDF has enabled me to view the proper format for the document, and I will be adjusting the HTML accordingly soon. Thanks

[Guest]

Yes, translating to PDF is quite trivial to some point. That?s the beauty of it too.

I have understood that Acrobat Word extension uses Adobe PDFWriter, which is the "fast but poor quality" solution. Distiller driver is better, and using it is not much more complicted than printing. When using Distiller you have more choices concerning compression/font embedding/quality etc.

Also, after the conversion to PDF is done, you have to create links, weblinks, clickable indexes etc. with Acrobat. So, when the final version (first "release") is ready, i could make the final PDF with all those things considered and implemented properly. (unlike in the "preview" version)

But I?m not very experienced in PDF?s yet (need to study a bit more), so if somebody has lots of experience with them and willing to take the job, it?s more than OK.



About the pictures in the manual, I think it?s ok that they are a bit squeezed vertically. It?s more friendly to the eye, specially when reading from screen.


In long term it would be best to make the manual in a carefully considered and structured XML-format. With the layout separated from content/structure, it would be easy to maintain/update the manual, and easy to publish in different formats.


I have an ongoing php-project, which will allow groups of people to manage information from a web-based content management system. It uses XML in the backend, including a system which automatically formats/publishes the same XML-data as fancy html/xhtml site or pdf, rtf, OpenOffice etc. documents.

It will take some tome to finish it, but maybe I could then structure the celestia manual to XML (which could be then edited/maintained by the celestia community/authors), and then make a tool which formats and "publishes" the document in all the different formats. Maybe.. just an idea.. as the manual as it is right now rocks already :)

-gaselli-

[slashi]

Agree with gaselli, XML would dramatically reduce manual's maintenance efforts. But the question is how this could be implemented?
Does anyone know about existing XML templates for user manual documents? With the authors permission I would try to develop the manual's maintenance guide which describes XML schema file, automated export procedures (into various file formats).