PDF Documentation ?

#1 This is the documentation: www.garagegames.com/docs/torque.sdk/index.php

(you might need to be a license owner to access that, I'm not sure)

#2 I am a licensed owner, but the thing is I cant log on everytime I want to check something, is there no downloadable help file ?

#3 You can build the documentation (such as it is) yourself using doxygen. Take a look at the makefile in the torqu directory for the proper command line.

#4 If you look in your torque/engine directory there is a file called "engine.overview.txt", this has a lot of information (in fact i think it's the same as the website) but it is in raw text form and is pretty ugly :(

#5 I have been working on updating the documentation over the holidays.

Using Doxygen you can generate a LaTeX document which can be converted into a PostScript document which can then be converted into a PDF... Whew! And it's about as easy as it sounds, NOT! But after hours of kicking my computer and tweeking Tex to handle the absurd number of pages I was throwing at it, I managed to generate a 1736 page Torque PDF, very nice.

I am considering replacing all the online HTML docs with the 5.3mb Zipped PDF download. Which would mean no more online-docs.

What are you thoughts?

--Rick

PS It would be much better to do:

Doxygen->XML->DocBook->PDF but I have yet to figure out if there is a solution for Doxygen XML->DocBook phase. If anyone knows of a solution please e-mail me.

#6 I'd rather the online docs don't disappear in favor of PDF.

PDF's are great for printing... but I just can't stand trying to scroll thru them.

So IMHO, having the only documentation being a 1700 page PDF being the only documentation.. bad idea. A PDF version of the online docs... good idea.

#7 I'd have to second the above post.

Also, I think the key thing with the doc's is the content + the ability for GG to keep it up do date, rather than the format it's delivered in.

Final thought - as there is alot of info spread out across loads of pages it would be good to have a high level summary of whats been changed (or if this already exists make it easier to find!)

#8 The PDF is hyperlinked so you can browse it just like a the current web pages. It is also searchable which the web page is not.

Basically they are the exact same content except that the downloaded PDF will be much faster than the website, searchable and have a more detailed index.

I would not host the PDF viewable via the web-browser, it's simply too large, it would be a download.

Providing a single PDF reduces my workload because the process is mostly automated and easy to upload to the website.

The html pages, all 1700 of them, are much more of a hassle to deal with and update to the site.

I am looking for a compelling reason to keep the html docs, the PDF seems to have it beat on every front.

--Rick

#9 Well... that answers my concerns - and at the end of the day - if it's easier for you to update then we will all benefit from that.

For some unknown reason I've never liked PDF's and so didn't think about the abiliy to search them - this is a real bonus over the web content.....

So I guess that gets my vote then....

#10 OK, PDF's are annoying and I cannot stand them. On-line documentation is more valuable than PDFs. Mainly because you can view them very easily on any computer that has internet access and if you want to have a copy on your harddrive then save it from the site. PDFs should never replace on-line documentation because that is a huge mistake. Sure PDF is portable, but come on people. PDFs are annoying, they suck in file size and quality, and I just cannot stand viewing them. Having code examples in PDF is a joke since you cannot highlight what you want and paste it into your script editor, so that blows PDF out of the water for that.

Let's see the facts:
PDFs:
* require a special program(Acrobat reader consumes too much CPU and Memory)
* are too big compared to what you could have with HTML and png images zipped in a zip file

On-line documentation(HTML):
* requires a web broswer(which we all apparently have)
* internet access(we all have this too)
* is low in file size therefore doesn't usually consume much Ram or CPU.


So with on-line documentation you already have everything needed to view it. With PDFs you need another application to view it. Acrobat reader is such a joke, it's image displaying sucks big time, takes way too much CPU and Ram, and it's a pathedic application to read page by page(so having a scroll wheel mind as well be required for this application).


So all in all, vote NO for PDF. :p

#11 You can copy-paste from a PDF by pressing 'v' to enter text selelction mode then just copy-paste like normal.

The zipped html+pngs are only about 500k smaller than the zipped PDF.

But the unzipped html+pngs are 10mb larger than the unzipped PDF.

Not trying to convince anyone either way just putting up the facts so we can decide what to do.

--Rick

#12 A distributable pdf guide would serve as a nice starting point for "beginners" and as a handy reference for advanced users... may evolve into .... "Torque Game Engine for Dummies" :)

#13 I'd really like to have the pdf version. Didn't took the time to figured how to make the doc with doxygen(too much other things to learn). Thanks Rick

#14 I think maybe have both? PDF would be useful when you can't get online etc. But cna you seach though a PDF easily?

And PDF I think are kind of annoying at times.

Maybe even if you made a html. downloadable version so its like a offline webpage? which could be easily updated.

#15 yeah a seperate offline and online version. You can take your time with the offline version only updating it with "stable releases"!

#16 Yes! I would love it if we changed to pdf, they are infinitely easier to deal with than html pages. Plus it's great for all those out there that use laptops.

#17 I'm curious, how is plain old HTML that can be viewed and edited by 100s of applications harder than PDF which is viewable by very few applications and editable by even fewer easier?

And how on earth is it more laptop friendly? Laptops have less RAM and smaller hardrives than desktops. A bloated format that requires special software can NOT be more friendly than the lighter weight HTML.

#18 Because it can be saved to a single file on your hard drive. And how can you not see the laptop point? How many people do you think have wireless access to view html files online?

#19 Tastes Great !

Less Filling !



;-)

#20 In summary so far:

PDF        HTML
-----------------------------------
Automated for GG   YES         NO
Printable          YES Not Really
Searchable         YES         NO
Copy/Paste         YES        YES
CrossPlatform      YES        YES
Viewer         Acrobat    Browser
Files                1       2362
Size              15mb       26mb
Zipped           5.3mb      4.8mb