Question to all users ...

[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?

[granthutchison]

"Doument format", Don?
Is that something French?

Grant

[Guest]

"Doument format", Don?
Is that something French?

Grant

The result above is much worse;-)

100% for the WORD "doument fragrance"...

Bye Fridger

[Guest]

"Doument format", Don?
Is that something French?

Grant

Nooooooooo, look at the result above:

100% for the WORD "doument fragrance"...

Bye Fridger

[Guest]

"Doument format", Don?
Is that something French?

Grant

Nooooooooo, look at the result above:

100% for the WORD "doument fragrance"...

Bye Fridger

[granthutchison]

For pity's sake, Fridger, log in! ;-)

Grant

[HankR]

I not really too particular about the format, as long as a free reader is readily available.

- Hank

[t00fri]

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

[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

Code: Select all

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

[don]

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

[don]

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.

[don]

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.

[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

[don]

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.

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.

[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

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

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

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

[Paolo]

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

[JLP]

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.