Celestia Users Guide Part 1 is complete - examine here

[ANDREA]

Hi everyone.
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.
Frank

Frank, as per my editorial experience I should choose Arial instead of Times New Roman, because it's more clear both in HTML and in .pdf format.
As a suggestion, but a suggestion only, I would like the possibility to change or add something as per my needs (for example, my sight is not so good as before, so I need to have bigger text fonts (12 instead of 10), and bigger images with more contrast) .
Well, with a .pdf format I could change nothing, while with any other format....
Waiting for part 2 and 3, thank you for your wonderful work, I discovered some functions that I completely missed previously.
By

Andrea
157 Frasso Sabino Observatory
RHP SpaceGuard Team
http://www.ara-frasso-sabino.org/andrea_celestia.htm

[Christophe]

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).

Of course there is an existing standard for manuals in XML. It's DocBook; there are stylesheets available for HTML or PDF convertion.

I will eventually make a docbook myself for the KDE version which uses an extended version of the official DocBook DTD, but if someone has already made a convertion from the Word document, that'd be a big help.

--
Christophe

[Dave007]

HTML update

I have experimented with Arial 12pt. font for the HTML version and it can be reviewed here.

fsgregs, as an option I could hyperlink the existing pics to popup larger versions if you wanted to go that route. Alternately, just changing the existing pics to larger pics is really no problem at all since they are embedded into invisible tables. Most people use 800x600 screen res, but I would recommend however that if you change the pic size, not to exceed 640x480 b/c some users who use that screen res would have scroll horizontally.

I'm not sure if my efforts are needed, so I'll just keep going

Best wishes

[Christophe]

HTML update

God! Looking at Frontpage generated HTML is depressing

Code: Select all

<td width="90%" height="19"><font color="#0000FF" face="Arial"><a href="#_Toc35497989">Select Objects by Keystroke</a> &nbsp;</font></td>
    <td width="10%" height="19"><font face="Arial"><a HREF="#_Toc35497989">
  18</a></font></td>

Don't they know at Microsoft that there is a thing called CSS? What are they after, NCSA Mosaic compliance?

--
Christophe

[Christophe]

Just to make things clear, I'm not disparaging anybody's effort, I just feel like it's going to be a maintenance headache and that a lot of time could have been saved or could be saved by starting from a properly marked up document in the first place.

Structure is everything, documentation authors should care about the structure (ie the meaning) only, the appearence is just a matter of applying a stylesheet it should be the last step. I guess people are just too used to WYSIWYG tools, they have their uses but producing documentation is not one of them.

--
Christophe

[Dave007]

I will work on "cleaning up" the code using CSS.

[selden]

Dave,

"It goes without saying" but just in case...
I trust you're creating a faiirly general script to do the cleanup and not doing everything manually. The procedure needs to be as painless as possible. Part 1 is undergoing extensive changes, so it'll have to be done again (and again..) and Parts 2 & 3 will be needing the same kinds of fixups.

[chris]

Dave,

"It goes without saying" but just in case...
I trust you're creating a faiirly general script to do the cleanup and not doing everything manually. The procedure needs to be as painless as possible. Part 1 is undergoing extensive changes, so it'll have to be done again (and again..) and Parts 2 & 3 will be needing the same kinds of fixups.

. . . not to mention the updates that will be required as new versions of Celestia appear.

--Chris

[fsgregs]

Hi everyone.

Thanks again for your continued input. The Guide is reaching critical mass now with many changes due to your great suggestions. That is good!!

I am sorry but my website friend has not had a chance to post the latest edited version of the Guide. Please watch my site. Maybe he'll get to it tonight. The new version is called Celestia User's Guide final-2.

I know absolutely nothing about XML or the schemes being discussed to maintain/edit future versions of the Guide. Sadly, I am swamped with projects and cannot devote the time to learn it. I suggest that we publish Part 1 and get it launched, and someone who has the time and skill can work on the document to set it up for updating more easily via XML techniques. If you wish to do so, please feel free. Likewise, if you need to modify the document in a bigger font for your own use, of course please do so.

I disagree that Times New Roman is inferior to Arial. I globally reformatted the document in Arial 10, 11 and 12, and several other fonts. Arial 11 and 12 are large type fonts and can obviously be seen easily, but in my perspective, they are too big. They give the document the impression of being a bit "massive" in text paragraphs. They also boost the document's length by several pages. Conversely, I examined the document in pdf Times New Roman 11 and found it pleasing to read. I checked several of my textbooks and found them all published in TNR 11 as well. As such, I would like to keep that font, at least in the MS Word .DOC format. If the HTML and pdf formats clearly look better in Arial to some folks, maybe we can take a poll or something.

Part 2 is about 40% written. If there is something I need to do to set it up for easier editing in the future, please let me know, or better yet, send me your e-mail address and I'll send you what I have so far. You can modify it as extensively as needed to facilitate its format/edit/etc.

I have not begun Part 3 and may not get to it for at least 2 months, due to the other projects I'm working on. Please be patient.

Frank

Thanks again for your input.

[selden]

If the HTML and pdf formats clearly look better in Arial to some folks, maybe we can take a poll or something.

My personal opinion is that the HTML version should have no font specifications whatsoever. Font face and size should be left up to the settings of the reader's browser. Also, its layout should not depend on any particular choice of font or size. (I am sick and tired of Web sites that specify teeny-weeny fonts that are invisibly tiny on high resolution monitors -- and then when your browser forces them to be large, separate paragraphs overlap one another, etc.)

Sorry for the venting...

[fsgregs]

OK, the revised version of the Users Guide with changes suggested by you all, is up on my site. Get it at
http://www.fsgregs.org/celestia. It is named Users Guide final, version 2.

We'll give it a day or two more, than call it a final print and begin getting it and its formats (pdf, html, etc.) onto the main Celestia site.

Obviously, it will be updated as new versions of Celestia come out. Thanks again for your support and comments. Special thanks to Selden for his extensive proof-reading.

Frank

[jim]

Hi Frank,

I found some short key bugs:

Galaxies ( U ) not ( Ctrl+U )
Orbits ( O ) not ( Ctrl+O )

PNG files are graphic files that are designed for viewing best on the Internet.

This is complete wrong! JPG is most times the best format for the web. Sure PNG works too but it's up to 10 times larger then JPG! Ask Fridger if you don't beliefe me. Only for some special cases if the picture has only few colors(<16) and fine details (e.g. script) can be the PNG format an alternative on the Internet.

Here is an typical picture example for PNG or GIF format.



For fotos and high color pictures use the JPG format on the Internet!

Now i think i should give a short guidance how to save Celestia shots in JPG format with low size and high quality. JPG's saved by Celestia are relative large and have only average quality. Therefore it's better to capture the image in PNG format. Then use an image editor or viewer (e.g. Photoshop) to save a optimized JPG. In the save dialog of your photo editor the JPG quality can be simple adjusteded. My favorite adjustments in Photoshap are: quality 7, several passes: 4 . My Celestia shots are most times smaller than 100kb and have a very good quality!

Expect this trifles the user guide is very good.

Bye Jens

[selden]

Which is the "best" image format depends on the use.

JPEG is a lossy compression format. You can reduce its "quality" setting and produce much smaller files representing a particular RGB image. However, the RGB image restored from a low-quality JPEG file will be much blurrier than the original because the high frequencies have been removed. The result is not the same as the original.

PNG uses a lossless compression format and is intended to replace GIF. Univac holds the patent on the compression algorithm used by GIF. You have to pay them royalties if you want to use that algorithm in software that you write. The PNG version of that same RGB image will be larger than the JPEG version, but the image restored from the PNG file will be identical to the original RGB image.

I hope this clarifies things a little [ahem]

[fsgregs]

Help!!

OK, I am confused about what to recommend in the guide. Specifically:

1. If Celestia can capture a screenshot in both jpg and png, should we always use png to save it in? If not always, when would we want to capture in jpg?

2. I was under the assumption that if one had a choice, they should use png files as textures in Celestia. I thought they loaded faster. Apparently, I may be wrong. If jpgs are smaller, do they load faster? If so, why not use them exclusively? Conversely, if pngs mean better functionality, why not convert all jpg files in the medres and hires folders to png files? Why use jpg's at all for textures (and there are lots of them used in the medres folder)? Likewise, since web browsers and virtually all word processing documents can display both png and jpg, what do we recommend to Celestia users?

If you would be kind enough to send me an edited version of the screen capture image paragraph that you prefer, I'll try to use it instead.

Thanks

Frank

[t00fri]

Help!!

OK, I am confused about what to recommend in the guide. Specifically:

1. If Celestia can capture a screenshot in both jpg and png, should we always use png to save it in? If not always, when would we want to capture in jpg?

2. I was under the assumption that if one had a choice, they should use png files as textures in Celestia. I thought they loaded faster. Apparently, I may be wrong. If jpgs are smaller, do they load faster? If so, why not use them exclusively? Conversely, if pngs mean better functionality, why not convert all jpg files in the medres and hires folders to png files? Why use jpg's at all for textures (and there are lots of them used in the medres folder)? Likewise, since web browsers and virtually all word processing documents can display both png and jpg, what do we recommend to Celestia users?

If you would be kind enough to send me an edited version of the screen capture image paragraph that you prefer, I'll try to use it instead.

Thanks

Frank

I think Selden explained things very clearly. It's all a matter of compromise: quality versus speed/file size. If you just want to show someone via mail/WEB an interesting astronomical event in Celestia, use the lossy but highly compressed JPG format. If you want to impress people in the forum;-) with the quality of your latest texture creation, definitely use lossless PNG format!

Bye Fridger

[jim]

Hi Frank,

If you want use a Celestia shot for Internet or email the JPG format is the best choice. But Celestia saves JPGs with an standard algorithm without any save otions. In a good photo edidor there are a lot of save options for the JPG format.

1. ...should we always use png to save it in? If not always, when would we want to capture in jpg?

This depend on how familar you are with a photo editor or viewer. If you now how to adjust the quality of JPGs in the save options of your photo editor/ viewer use the PNG format to capture an image in Celestia. After that open this image with your photo editor/ viewer and save it as JPG. With the right settings the quality can be significant better by smaller files than a JPG shot in Celestia.
If you have no idea how to do this save your shots direct as JPGs.

2. I was under the assumption that if one had a choice, they should use png files as textures in Celestia. I thought they loaded faster. Apparently, I may be wrong. If jpgs are smaller, do they load faster? If so, why not use them exclusively? Conversely, if pngs mean better functionality, why not convert all jpg files in the medres and hires folders to png files? Why use jpg's at all for textures (and there are lots of them used in the medres folder)? Likewise, since web browsers and virtually all word processing documents can display both png and jpg, what do we recommend to Celestia users?

The reson why celestia comes with predominat JPG texture is that chris tries to make the download as small as possible. If you had the choice use DDS files but that's not the answer you want. Now today with the power of our computers Celestia loads JPG and PNG files similar fast because most time is needed to build the mip maps or free up more memory by useing the swap file. In the memory (not on disc) JPG and PNG files have the same size. If you save a textures in jpg with high quality then you will have no (visible) difference in quality to a PNG texture. But there is one importent difference between JPG and PNG files PNG can save an alpha channel. This is necessary for clouds (transparency) and usefull for planets with specular reflections.

If you would be kind enough to send me an edited version of the screen capture image paragraph that you prefer, I'll try to use it instead.

I made this already look in a previous post of me but translate this in a good enlish.

Ok, have i all questions now answered or is something still confused?
Look for more information at my post about textures!

Bye Jens

[fsgregs]

OK, since we have not received comments in a few days, review time for Part 1 of the User's Guide is completed. Thanks to all of you for your great comments. Special thanks to Selden for his detailed proof-reading.

I have modified the document to incorporate your comments and it is now in final form. I have sent it to my webmaster host who hopefully will post it on my website for final examination. I have also sent it to Chris for posting on the Celestia site. We will now need it converted to html and pdf. Anyone willing to do it, please do so.

Thanks again.

Now, on to Part 2.

Frank G

[Christophe]

I've converted it to docbook and HTML:
http://teyssier.nerim.net/celestia/doc/index.docbook

All on one page:
http://teyssier.nerim.net/celestia/doc/index-nochunk.html

KDE doc:
http://teyssier.nerim.net/celestia/doc/index.html

I had to redo the screenshots to add the cel URLs but they don't look as good as yours, I might change them back or if you've got time could you regenerate them from the URLs?

I've also made some minor corrections and additions relative to the KDE version.

I'll run a diff on the final version to incorporate your latest changes.

--
Christophe

[selden]

Christophe,

Attempting to open your first URL using Internet Explorer v6.0SP1
generates the error message

Code: Select all

The XML page cannot be displayed
Cannot view XML input using style sheet. Please correct the error and then click the Refresh button, or try again later.
--------------------------------------------------------------------------------
The system cannot locate the object specified. Error processing resource 'http://teyssier.nerim.net/celestia/doc/dtd/kdex.dtd'.


The other two display reasonably well.

[Christophe]

Well, you're not really supposed to look at the docbook file with a browser anyway, it's the source file, best viewed with a text editor.

IE is trying to validate it but can't find the DTD and so spits out an error. I'll upload the DTD later on today.

--
Christophe