Page 1 of 2
Question to all users ...
Posted: 23.12.2003, 21:12
by don
Seasons Greetings Everyone,
Currently, a few of us are discussing the pros and cons of various documentation file formats in the Celestia SourceForge Developers mailing list -- for things such as the User's Scripting Guides.
So far, we have found several Pros and Cons with each of the file formats being discussed (hyperlinks are where you can click a link and have an example
Cel://URL open in Celestia, or be taken to a web page) ...
Code: Select all
Format Pros Cons
------- --------------------- --------------------
Text Small file size. No images/graphics
For Unix/Linux users. or hyperlinks.
RTF Small file size. No hyperlinks.
Allow graphics.
For Unix/Linux users.
Word For Windows & Mac Large file size.
users. Allow hyper-
links.
PDF Nicely formatted. No hyperlinks.
For all users. Large file size.
Indexed Quick loading. No search.
HTML Allow hyperlinks.
For all users.
One Big Allow search. Slow loading.
HTML Allow hyperlinks.
For all users.
I am curious to know what format(s) you prefer, based on the operating system you use to run Celestia, and would appreciate your feedback. However, since the Poll feature does not allow multiple questions, or multiple answers, all I can ask is a single question and you may only reply with a single answer.
So ... regardless of your OS, which is the document file format you would most want to have in order to view the Celestia User's Guide, .CEL Scripting Guide, Lua Scripting Guide, etc., where images, and the ability to click on a hyperlink are built-into the document itself?
Posted: 23.12.2003, 22:41
by granthutchison
"Doument format", Don?
Is that something French?
Grant
Posted: 23.12.2003, 22:47
by Guest
granthutchison wrote:"Doument format", Don?
Is that something French?
Grant
The result above is much worse;-)
100% for the WORD "doument fragrance"...
Bye Fridger
Posted: 23.12.2003, 22:50
by Guest
Anonymous wrote:granthutchison wrote:"Doument format", Don?
Is that something French?
Grant
Nooooooooo, look at the result above:
100% for the WORD "
doument fragrance"...
Bye Fridger
Posted: 23.12.2003, 22:52
by Guest
Anonymous wrote:Anonymous wrote:granthutchison wrote:"Doument format", Don?
Is that something French?
Grant
Nooooooooo, look at the result above:
100% for the WORD "
doument fragrance"...
Bye Fridger
Posted: 23.12.2003, 23:04
by granthutchison
For pity's sake, Fridger, log in! ;-)
Grant
Posted: 23.12.2003, 23:33
by HankR
I not really too particular about the format, as long as a free reader is readily available.
- Hank
Posted: 23.12.2003, 23:46
by t00fri
granthutchison wrote:For pity's sake, Fridger,
log in!
Grant
'8O' Normally, I am always logged in, but when I had typed those beautifully colored WORD "
doument fragrances, the system instantaneously decided to
log me out 
What can I do. No guest edits possible...
Bye Fridger
Posted: 24.12.2003, 03:56
by selden
A correction: PDF format does indeed support hyperlinks. I've encountered many documents which have them.
Of course, I personally don't have the slightest idea how it was done. I've never written anything in that format.
Personally, I prefer HTML format. No matter what the size, an HTML document takes less time to load than the equivalent (much larger) PDF or Word document. It also provides a lot more leaway for changes in presentation format by the reader. There are those of us who can no longer read dark blue 3 point text on a black background.
Added somewhat later:
My preference for HTML is based on the assumption that the documentation will be maintained using direct editing of HTML source code with a plain-text editor, perhaps augmented with a simple emacs macro or equivalent for highlighting and testing simple things like tag validity. WYSIWYG editors are a non-starter for this. They generate a lot of spurious coding in order to make sure that the pixels seen on the screen by the reader are exactly what the author saw.
Simple document format coding is a requirement. For example, it's enough to indicate a paragraph break with simple
-- specifying the amount of indentation, two line capitalization, etc. is unnecessary and inappropriate.
For the author to specify fancy formatting, font size, coloration and the like which are enforced by presentation software usually is
not appropriate in computer software documentation. Many of the presentation details
must be left to the reader.
Posted: 24.12.2003, 06:31
by don
granthutchison wrote:"Doument format", Don?
Is that something French?
Grant
What, you don't know what a doument is?
I thought everyone knew what a doument was.
Sorry, the forum software won't let me edit the Poll. Oh well. Just shows how well I *really* type with my two-fingers-and-a-thumb method.
-Don G.
Posted: 24.12.2003, 06:34
by don
selden wrote:A correction: PDF format does indeed support hyperlinks. I've encountered many documents which have them.
Only if you have the Adobe Acrobat software ($250+) AND re-enter the hyperlinks manually. Even the Adobe PDF Creator on their web site does not convert hyperlinks.
At least not from a Word document.
Maybe one of the DocBookBoys can try adding a hyperlink or
Cell://URL to a docbook document and see if it gets converted into PDF format?
-Don G.
Posted: 24.12.2003, 06:42
by don
selden wrote:My preference for HTML is based on the assumption that the documentation will be maintained using direct editing of HTML source code with a plain-text editor, ...
I understand. Unfortunately, the HTML would be auto-generated from a DocBook format XML document. Here is some example output using a KDE Stylesheet:
http://celestia.teyssier.org/doc/.
IE has decent Accessibility options, that I use all the time. Due to cataracts in both eyes, I can't look at white backgrounds. So, I disable page-encoded backgrounds and use my Windows defaults (Black text on a Silver background). Works fine on this example page. I also use the Text Size option quite a bit and it too works on this page.
-Don G.
Posted: 24.12.2003, 06:57
by Bob Hegwood
Don,
Does this mean you've gotten something more to put INTO the preferred format?
After having researched, investigated and otherwised beaten myself to death over trying to understand the Central Meridian concept (See
http://www.shatters.net/forum/viewtopic.php?t=3996 for more information), I would have very much welcomed an informative document of *any* kind on this topic. Whew!
Thanks, Bob
Posted: 24.12.2003, 07:56
by don
Bob Hegwood wrote:Don,
Does this mean you've gotten something more to put INTO the preferred format?
No, not at this time Bob. What we are discussing is how to use a *single* document format, such as DocBook, in order to then auto-generate ALL other user-requested / desired formats. This would greatly reduce the amount of time and effort required to keep all Celestia documents updated and available for all platforms.
Bob Hegwood wrote:After having researched, investigated and otherwised beaten myself to death over trying to understand the Central Meridian concept (See
http://www.shatters.net/forum/viewtopic.php?t=3996 for more information), I would have very much welcomed an informative document of *any* kind on this topic. Whew!
Sounds like a couple of good drawings might have helped there.
Cheers,
-Don G.
Posted: 24.12.2003, 08:27
by Bob Hegwood
Don,
A couple of drawings would have been nice, but PLAIN English explanations are MY cup of tea.
Without Mr. Hutchison's extreme patience and understanding, I would *never* have figured out what the hell everyone was trying to explain to me.
Take this advice from me... Have Grant proof-read everything you want to publish. He, at least, knows how to communicate a concept to us poor slobs who have never even heard of the term "Central Meridian."
I do love your guides though. They give me just enough information to be dangerous.
As always, thanks again, Don.
Take care, Bob
Posted: 24.12.2003, 08:54
by don
Bob,
Sounds like what I went through trying to understand what "up" meant, in the setframe command, and what a Coordinate System was. Still not positive that I could draw a diagram of each of the Coord Systems. Astronomy, Celestial Mechanics and Astrophysics are not "simple" topics for the un-educated (in these topics) to understand, regardles of our existing education or experience. In laymen's terms, it is sometimes difficult for scientists to communicate effectively to laypeople.
I basically wrote the Scripting Guide as I learned things for myself, so it should be at a level that any new Celestia user can understand -- hopefully. Glad to hear it's made you "dangerous", as this is the best way I usually learn too -- by getting myself into trouble.
Cheers,
-Don G.
OpenOffice.org
Posted: 24.12.2003, 10:26
by JLP
I think that the document format should be open and as portable/crossplatform as possible. So maybe it could also be in OpenOffice.org format. The files it makes are very small and the office suite is opensource and available for many operating systems and in many languages. It also has support for exporting PDF files with hyperlinks. The next prefered format after OpenOffice.org is PDF and then HTML.
Posted: 24.12.2003, 18:40
by don
Howdy JLP,
I never thought of OO org as a "format", but you are absolutely right. Do you know if there is an OO org "reader" so folks would not have to install the entire app?
Happy Holidays!
-Don G.
Posted: 24.12.2003, 19:25
by Paolo
selden wrote:Personally, I prefer HTML format. No matter what the size, an HTML document takes less time to load than the equivalent (much larger) PDF or Word document. It also provides a lot more leaway for changes in presentation format by the reader. There are those of us who can no longer read dark blue 3 point text on a black background.
My preference for HTML is based on the assumption that the documentation will be maintained using direct editing of HTML source code with a plain-text editor, perhaps augmented with a simple emacs macro or equivalent for highlighting and testing simple things like tag validity. WYSIWYG editors are a non-starter for this. They generate a lot of spurious coding in order to make sure that the pixels seen on the screen by the reader are exactly what the author saw.
Simple document format coding is a requirement. For example, it's enough to indicate a paragraph break with simple <p> specifying the amount of indentation, two line capitalization, etc. is unnecessary and inappropriate.
For the author to specify fancy formatting, font size, coloration and the like which are enforced by presentation software usually is
not appropriate in computer software documentation. Many of the presentation details
must be left to the reader.
My two half cents.
I completely agree with Selden. Simple indexed HTML.
Seasonal greetings and Merry Christmas to everybody
.
Bye - Paolo
OpenOffice.org Viewer
Posted: 24.12.2003, 19:37
by JLP
don wrote:Howdy JLP,
I never thought of OO org as a "format", but you are absolutely right. Do you know if there is an OO org "reader" so folks would not have to install the entire app?
Happy Holidays!
-Don G.
If I am not wrong there is no viewer only app for OpenOffice.org. I think I have seen a page for some Java based viewer but back then I couldn't find I link to download it. maybe there now is a viwer somewhere. I'll try to look for something usefull.