Paul, Your points are well taken.
I took a pretty close look at JavaHelp. If you are a fan of HTML help it is the way to go. I decided against using Java help because I wanted a way to cleanly separate text from images. If I was to use a help documentation system that didn't use PDF, I would create a simple GUI that could display simple text and images in a logically separated way. I suppose you could use HTML if you didn't care about layout for printing, and you could put all images in separate HTML pages... I might be open to that idea. In this case I would be open to using Java Help. The only thing I don't like about this approach is that HTML really stinks for printing. So if we wanted good "printable" use documentation we would end up using a word processor or program like Scribus anyways. An alternative would be something that could produce HTML and PDF from plain text. I think DocBook does this, but every time I think about using it I shy away because of the learning curve. I'd like us to continue this dicussion. If we can figure out a compromise that works for most of us I'll scrap the PDF help idea. So, does anyone have a FOSS solution that we could use to automatically produce PDF and HTML PDF documentation from the same plain text source? We could throw the HTML into JavaHelp and make the PDF available for download to those that want a copy of the docs they can print. I'm open for suggestions. The Sunburned Surveyor On 10/17/07, Paul Austin <[EMAIL PROTECTED]> wrote: > Landon, > > On the P.S.S. Documentation that is larger because of quality > descriptions and illustrations is a good think. Larger because of file > format size is not so good. > > Another thing is responsiveness, on my Linux box it takes forever to > launch a PDF viewer, an embedded swing HTML viewer however is really > fast. The other thing we should look at is the Java Help system to see > if it meets out needs without inventing things ourselves. > > Paul > > > Sunburned Surveyor wrote: > > Paul brings up a good point. > > > > The only thing I don't like about HTML is that your options for > > controlling layout are limited. I think it also presents some > > challeneges in the separation of text and images, which I think is > > important for translation. Printing HTML docs can be tricky too. > > > > I've done work on a simple help viewer. It basically does what Larry > > talks about, but also includes support for images. I could use it > > instead. But that would take a week or two of work...I'll have to chew > > on it. > > > > You could probably look at the issue this way: > > > > Disadvantages of PDF help documentation: > > - Size of files. > > - External Viewer Needed > > > > Advantages of PDF help documentation: > > - Exact control over document layout. > > - Easy hard copy printing. > > - Access to documentation from outside the application. > > - Common document format. > > > > I think for something like a Plug-In I would include the PDF files in > > the download. For something like a user or developer manual I would > > package the PDF as a separate download. > > > > I guess I'm just a fan of PDF. :] It must be the graphic artist in me. > > Still, this discussion is good, as I hadn't considered the size issue. > > > > If someone is willing to develop an alternative help system that will > > be supported in OpenJUMP, I will strive to make my plug-in help docs > > conform. > > > > Thanks. > > > > The Sunburned Surveyor > > > > P.S. - Larry: On my Linux system the PDF viewer is FOSS. > > P.S.S. - Paul: In my perspective PDF documentation that is larger than > > the actual code is a sign of a well documented program, which most > > FOSS is not. I think there are several popular FOSS programs where the > > help docs are larger than the code base. > > > > > > On 10/17/07, Paul Austin <[EMAIL PROTECTED]> wrote: > > > >> And if you need to have some pretty formatting or images use HTML. > >> > >> On another perspective on the issue. HTML is a fairly low overhead way > >> to encode text. PDF files on the other hand have a lot of overhead. > >> > >> If we look at this one page PDF it takes up 164KB where as a HTML > >> document with image would probably be 5kb. > >> > >> If we have 1000 functions in OpenJUMP with 1 page of help the PDF files > >> would be around a 164MB download as opposed to about 2MB with HTML (my > >> math is correct the image 3KB is shared across all the pages in the HTML > >> with only 2KB of text that differs). > >> > >> Just another way to think about it. Your help files should not be bigger > >> in size than the code! > >> > >> Paul > >> > >> > >> Larry Becker wrote: > >> > >>> PDF is just a non-standard way to do help. All you have is some > >>> text. You should just pop up a window with a text component and > >>> display it. Don't make me open another (non-free) application to view > >>> your help. > >>> > >>> Larry > >>> > >>> > >>> > >> ------------------------------------------------------------------------- > >> This SF.net email is sponsored by: Splunk Inc. > >> Still grepping through log files to find problems? Stop. > >> Now Search log events and configuration files using AJAX and a browser. > >> Download your FREE copy of Splunk now >> http://get.splunk.com/ > >> _______________________________________________ > >> Jump-pilot-devel mailing list > >> Jump-pilot-devel@lists.sourceforge.net > >> https://lists.sourceforge.net/lists/listinfo/jump-pilot-devel > >> > >> > > > > ------------------------------------------------------------------------- > > This SF.net email is sponsored by: Splunk Inc. > > Still grepping through log files to find problems? Stop. > > Now Search log events and configuration files using AJAX and a browser. > > Download your FREE copy of Splunk now >> http://get.splunk.com/ > > _______________________________________________ > > Jump-pilot-devel mailing list > > Jump-pilot-devel@lists.sourceforge.net > > https://lists.sourceforge.net/lists/listinfo/jump-pilot-devel > > > > > ------------------------------------------------------------------------- > This SF.net email is sponsored by: Splunk Inc. > Still grepping through log files to find problems? Stop. > Now Search log events and configuration files using AJAX and a browser. > Download your FREE copy of Splunk now >> http://get.splunk.com/ > _______________________________________________ > Jump-pilot-devel mailing list > Jump-pilot-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/jump-pilot-devel > ------------------------------------------------------------------------- This SF.net email is sponsored by: Splunk Inc. Still grepping through log files to find problems? Stop. Now Search log events and configuration files using AJAX and a browser. Download your FREE copy of Splunk now >> http://get.splunk.com/ _______________________________________________ Jump-pilot-devel mailing list Jump-pilot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/jump-pilot-devel
