PDF Documentation ?

#21 I think we have a winner folks! :)

#22 It seems obvious that Rick knows what he wants, and he has the keys, so why bother posting?

And no doubt with only a few more hours of education in the ways of Adobe's Acrobat I could learn to overcome my personal shortcomings that cause me to fail to love such a perfect product.

But I receive a lot of documents in PDF already, and it's a pretty sucky way to get doumentation.

Let's review:

Automated for GG? Apparently already true for PDFs, but could be made true for HTML as well--or instead since HTML is a lot easier to generate. PDF is a proprietary format. If that weren't true, it would already be a one-button-press process to export it to a set of html files, or to view it and search it online using an apache plug-in.

Printable? A 1700 page document is not really printable in any format.

Searchable? No reason online docs aren't searchable. a definite PDF advantage for off-line viewing. Coalescing the HTML into a single file wuld accomplish the same thing but your browser would choke. Not sure I care, though. Not a substitute for a good table of contents.

Viewable? HTML--sure. PDF? Not very:
Acrobat formats pages as if they were on paper: with margins and half again as tall as they are wide. You use one method to scroll down in the current page, and a different method to scroll to the next page. PDFs almost always start out in a font that is unreadably tiny, then you zoom them in until the text is legible, which causes the (pointless) margins to be wider than your screen, so then you use the horizontal scroll bar to position the text where you can see it.

PDF is a page-layout format which also means that it has poor support for changing the window size. I just resized this window so it was tall and narrow, then as short and fat. In both cases the current paragraph remained entirely in view. This ability can be a boon when comparing documentation to code side by side.

The current HTML docs prevent access to certain sections by unregistered visitors. I don't believe PDF supports this.

PDF will mean a 15MB (5.6MB compressed) file needs to be downloaded every time a word of documentation is changed. HTML would be updated page-by-page using CVS, or with an IMS check online still only downloading changed pages.

I have received many PDFs in my day, and every one that was over a few MBs has been broken up into multiple sections (which kills the searchability feature). Don't know why, but assume viewing 15MB PDFs could have problems on some hardware--maybe that's an obsolete problem. No link to the PDF was provided in this thread or in the doc section, so I couldn't observe its characteristics for myself.

#23 Might there be a way for GG to generate the html automatically from either the PDF or the LaTeX file? If you could automatically generate the html, then you wouldn't have a hard time keeping it up to date alongside of the pdf, and everyone would be happy.

Of course, I'm not sure how feasible this is. I'm pretty sure you can convert it to html, but I don't know if the link will be correct when referenced online. Maybe a small script could go through and fix all the links...I don't know. Just some thoughts.

#24 I *hate* receiving online documentation in PDF form. The file format just isn't designed for it. It's great for things one needs to print, like forms, where preserving exact page layout matters. It's terrible for on-screen reading, thanks to font inflexibility and its inability to re-flow pages when one resizes the window.

Nobody is going to be printing a 1700-page document. So pdf's single advantage is useless in this case, and you're left with all its disadvantages.

I'd much rather get access to a CVS repository of the html files. A single tarball of the lot would be fine too. I can grep those for a poor-woman's full-text search. When one section gets updated, I need only re-download the affected section. I can read the documentation in a screen-reading-friendly browser that is designed to reflow pages.

#25 Just to be clear -- I do not have my mind made up. It really doesn't matter what I think at all, it is entirely about what is most useful to a majority of the Torque developers.

Sample PDF Page

--Rick

#26 /ME likes PDF, too.... :D
*hides*

#27 Rick,

Whilst others may not like the idea of PDF's, I do. The only time I think it would be inconvenient was if the documentation was constantly changing which it isn't.

I really don't understand the problem some people have with PDF's. We convert the most comprehensive technical data / manuals at work into it as, coupled with indexing, it provides a neat packaged solution. Each to their own I guess.

The only thing I don't like about it is when you've got documents with more images than text. For some reason the drawing of these images can be really slow at times.

You're seem hard at work there buddy, thanks for the effort.

- Melv.

#28 That sample PDF page looks pretty good to me.

#29 A) I have displayed in my Acrobat a document labelled 'IA32 v2' which is Intel's instruction set reference for pentium+ processors. It is 6.5 megabytes and 956 pages long. It takes 1 minute 40 seconds to search through the entire document for a simple string. It wraps various entries inside tables, such as the "compiler intrinsic equivalent" for UNPCKHPD in table C-1; when you select from beginning to end of the intrinsic you also get parts of the adjacent table entries: this does not usually happen in HTML (where bizarre table choices sometimes make selecting more than one column exciting.

B) I am surprised to hear people say the document won't change much, since many and valuable portions are simple "to be documented later" and since the engine and such are also changing (i.e. Melv's contributions should be documented).

#30 I vote for both if possible, HTML if only one must be chosen. PDF is a great format, but it's just not right for this kind of extensive, rapidly changing documentation. HTML is zero-effort to use for the end-user; PDF requires a download, and re-download when the doc changes. HTML displays by default in a very reasonable format; PDF displays by default in an almost unreadable zoomed out format.

PDF is great for printability, but I almost never print docs out. I certainly won't be printing 1700 pages anytime soon ;)

But what WOULD be really useful, would be a doc site like at www.php.net and www.mysql.com, where they present the documentation in various formats (all on one page, page per section, page per chapter, etc.), including allowing user contributed notes.

This is the SINGLE most useful part about the documentation being online for these tools. If I look up a function in PHP, there is the Official reference online. But say it was added very recently, and I'm running PHP3... Chances are there is a backport. There are also _many_ examples. If I already know what's going on, I can just read the first screen's worth of information. If I'm unsure, there are usually several examples and lots of tips - "watch out for this", "this can be a security hole", "this other way is faster".

And all this without any effort on the part of the document maintainer!

I think that adding this kind of functionality to the Torque docs would be invaluable, especially for the class references and such. Perhaps a small corps of users could be blessed with the ability to add comments, to keep the information accurate... however, the PHP site has a good approach:

PHP Link

That URL is where you get sent when you want to post a note. The button to add a note is relatively lowkey, so that people aren't encouraged to treat it like a forum, and the warning at that page makes it doubly clear.

Something like this could be of great use for everyone.

But it would take some work :), though you'll note that you can view the source of any page on the PHP website.

And don't forget, my vote is for html as a necessity, PDF as a luxury.

#31 The ability for user-submitted annotations on the documentation could be a great boon, IMO.

#32 I am beginning to wonder how deep this documentation rabbit hole goes...

What started out as my curiosity generating a Doxygen'ized Torque PDF has evolved into a mini research project to discover how GarageGames should approach the generation of documentation in the future.

Solving one problem at a time...

I downloaded the Doxygen source code this weekend and made some modifications and added a configuration option that would allow me to omit the file list index. We don't need a file list index for the Torque documentation it is redundant and trims more than 1500 pages from the output bringing the docs down to the approximately 1700 pages I mentioned above. One step closer.

I submitted the change to Dimitri (author of Doxygen) so hopefully it will show up in the next stable release of Doxygen, version 1.3. Open Source Rules!

The big picture...

So far we have only been discussing Torque source code documentation but I would really like a solution for all GarageGames documentation: tutorials, examples, source docs, etc. We have a lot of great information on this site but some of it is in our databases, some in html, some in php, a little here, a little more over there. I do not want to make a single massive document (although publishing a book one day would be cool, "Indie Gems"...) it would be nice to have a single unified meta format from which we could generate whatever we want.

A little further down the rabbit hole: DocBook XML

DocBook XML DTD seems to be the direction the OpenSource community is going. PHP.net, the Linux Documentation Project, etc, all use DocBook. DocBook is nothing more than an XML document type definition; you need other tools to translate it into the desired output formats like HTML/PHP, CHM, PDF, Postscript, etc. Saxon seems to be the most popular XSLT used to generate HTML and text documents. And it looks like you can use Saxons xsl:fo output with Apache FOP (Formatting Objects Parser) to generate PDF files.

A call to action!

I believe DocBook is the light at the end of the tunnel but it is not an instant fix, it is going to take a lot of work, way more than I can handle myself. If I can find a couple of talented GG community members to assist I would like to launch a GarageGames documentation project to convert existing documentation into DocBook format and establish a build system to create HTML, PHP and PDF documentation. If we want to include the Torque source code documentation we still need to solve the problem of converting Doxygen's XML output into DocBook XML. Someone just needs to write an XSLT to do the work.

Anyone interested in helping out please let me know. And post your thoughts here.

--Rick

#33 Count me in on the PDF. Nice to have a portable and searchable version of the docs.

#34 A properly formatted, linked and designed PDF file will always win over RAW HTML.

That said I have seen PLENTY of PDF files as "documentation" that were nothing more than Word documents printed out to PDF.

Based on the sample page Rick posted above, I think that the PDF file would be very valuable. And if others wanted the HTML then they can create it with Doxygen.

That all said, searchable HTML would me nice also but I would rather have searchable FORUMS before anything else!!!

@David Zink: People say the documentation doesn't change because no one is really working on those TBD or updating the outdated parts as a full time job right now. Realistically it won't be changing anytime soon probably and if it does you just re-gen the PDF just like you would have to re-gen the HTML.

#35 Why don't we just bite the bullet, and make a unified approach? I think the only way everyone will be satisfied will be with both... which probably means DocBook or some other unified solution.

Rick - have you tried e-mailing the documentation maintatiners for some of the larger open source projects? A lot of them have as much/more docs than we do...

#36 Just another vote: PDF.
For the fact that it is searchable and usable offline. If it is hyperlinked and has an index, all the better.
-Ed

#37 If BOTH versions can exist, then by all means .PDF...
(BUT a .PDF file needs to downloadable for licensed
torque users ONLY)

If it is one or the other then I'll vote NO for .PDF...

#38 Rick - I'm all for PDF documentation. I'm usually more interested in havin' docs here on my machine (not that you can't do that with HTML), and tend to prefer the PDF format for various reasons.

I'd volunteer to help ya' get it all reformatted, but, I'm way past my release date on TZ at the moment - business first ;-)

#39 I did a little searching and came up with the following project on sourceforge:

Project: Doxygen-Docbook XSL Stylesheet

They have not released any files yet, but they do have files in their CVS, which as of now was last updated 14 days ago.

#40 LabRat, you made my life easier once again ;)
-Pat (KillerBunny from way back when)