OSDev.org

What do people prefer? What seems easier to understand?

These references are no where near complete - I've only inserted a few functions in both to compare.


Here's my online application programming guide:
http://messiahandrw.netfast.org/Percept ... mentation/

Here's my printable/PDF application programming guide: http://messiahandrw.netfast.org/Percept ... on/apg.pdf

nice a poll and about 3 or 4 posts about pdf and doxygen in the last few hours. somebody is obsessed

I prefer online. Printing pages and pages of documentation is a major waste of ink.

Alboin wrote:I prefer online. Printing pages and pages of documentation is a major waste of ink.

I prefer printed. I can't note on online documentation enough, the input & output mechanisms are too limited and all the online docs come without markers, the ability to tear, be recombined, moved about, read without log at work and so on. Also, I have a laserprinter so I won't be wasting ink.

I like PDFs because they are so much easier to download. I usually don't make any printouts of any of my resources, so the ability to print usually isn't that important. I also like that in pdfs all of the information is in one file and is easily searchable.

Hi,

Seems like an easy choice for me - a fully open standard that is supported by every OS any sane person would actually use, or a partially proprietory standard that is poorly supported on every OS except Windows?

Let people convert the HTML to PDF if they really need PDF, and let people download the HTML as a single file or as a "file per chapter tar.gz" for offline viewing, or read it directly from your web site for online viewing (and the lete Google parse it so people can search for your function names, etc).


Cheers,

Brendan

Brendan wrote:Seems like an easy choice for me - a fully open standard that is supported by every OS any sane person would actually use, or a partially proprietory standard that is poorly supported on every OS except Windows?

Point of order -- PDF is actually very well supported on Mac OS X. I would say it's supported even better than on Windows.

That said, I prefer HTML docs because of the hyperlinks. I use Doxygen for my OS project and at work too.

Colonel Kernel wrote:That said, I prefer HTML docs because of the hyperlinks.

Most word processors that export to PDF also automatically index the PDF and add in-document links (e.g. clicking an item in the contents menu will take you to that page).

btw. Nice name

Brendan wrote:...a fully open standard...

I couldn't care less about "open" or not, as long as it works.

...that is supported by every OS any sane person would actually use, or a partially proprietory standard that is poorly supported on every OS except Windows?

I didn't have problems watching PDFs on any of my machines, including a 240x320 pixel PDA display that played havoc with all but the most basic websites.

Let people convert the HTML to PDF if they really need PDF...

Any non-trivial online documentation is multiple pages, and I've seen countless of those who did not offer an "all in one page" or "all the docs in one tarball" option. If they would, that would be OK with me, but too many people think that...

...or read it directly from your web site for online viewing...

...online viewing is possible and / or desirable for everyone.

PDF gives you a choice (online or printout), HTML ranges from "less comfortable" to "useless". (Point in case: The Lisp Primer. 116 HTML pages, no alternatives.)

Personally, I definitely prefer PDF, the longer the docs the more my preference. I can't read a laptop on the balcony in the sun, I can't comfortably read a laptop in my lounge chair. I can do so with a book or a printout.

I've seen too many badly written, badly thought-through HTML docs, in bad layouts, to really believe in the "it's the more techy way to do it". In 90% of the cases it's lazyness / carelessness, IMHO.

I can not decided really. I actually prefer a PDF if the content has settled a lot since this lets me never have to worry about having to have a internet connection to read it.

But, sometimes I read the HTML documentation:

• To keep from eating more resources by opening my PDF reader.
• To not download something and have to take time to place it somewhere.
• If it is rather large to download and might take more time instead of reading a select part of it online.

I think people should offer the two versions which now reminds me that maybe I should do what I preach and make a PDF of my documentation for the kernel source I have.. Makes sense huh?

Hi,

Solar wrote:

Brendan wrote:...a fully open standard...

I couldn't care less about "open" or not, as long as it works.

For an OS developer, in the long term it doesn't make much sense to rely on standards that can't or won't be supported by your own OS. It'd be embarrasing and/or annoying to have a fully self-hosted OS where programmers need to use someone else's OS to read the programming documentation.

Solar wrote:

...that is supported by every OS any sane person would actually use, or a partially proprietory standard that is poorly supported on every OS except Windows?

I didn't have problems watching PDFs on any of my machines, including a 240x320 pixel PDA display that played havoc with all but the most basic websites.

I'm using "xpdf" on Linux, which has horrible performance (in a large document, try holding down the "page-down" key for 5 seconds and see how long it takes for the video to catch up). Mozilla doesn't have this problem.

Solar wrote:PDF gives you a choice (online or printout), HTML ranges from "less comfortable" to "useless". (Point in case: The Lisp Primer. 116 HTML pages, no alternatives.)

On my Linux/Mozilla machine, PDF gives you the choice of "save as" or attempting to open it with some application. There's no way to open it in a browser window (e.g. in a browser tab).

Would The Lisp Primer be "less comfortable" if it was available as 116 PDF files with no alternatives?

Solar wrote:Personally, I definitely prefer PDF, the longer the docs the more my preference. I can't read a laptop on the balcony in the sun, I can't comfortably read a laptop in my lounge chair. I can do so with a book or a printout.

Why is it harder to print HTML files than it is to print PDF files?

Solar wrote:I've seen too many badly written, badly thought-through HTML docs, in bad layouts, to really believe in the "it's the more techy way to do it". In 90% of the cases it's lazyness / carelessness, IMHO.

Bad documentation is bad documentation regardless of which format it's in, and I'm sure that if the badly thought-through HTML docs were converted into PDF format they'd still be badly thought-through.

IMHO the only real problem with HTML is that pictures can't be embedded into the same file, but I doubt this matters much for documentation converted from ASCII source code.


Cheers,

Brendan

Brendan wrote: Why is it harder to print HTML files than it is to print PDF files?

That one could be obvious in certain situations. I for one have to disagree that printing certain HTML hierarchies is just as easy as printing a PDF book.

Also if I take your statement exactly like you wrote it then I would assume to have these HTML files in a packaged manner which in this case you should be correct. But, from Solar's earlier post with reference to "(Point in case: The Lisp Primer. 116 HTML pages, no alternatives.)" I think you might have dodged the argument he is trying to make.

To turn around against the point Solar made there exists wget and it's recursive downloading if I am not mistaken, and if I am right does exist a tool that works nicely IIRC if wget does not - this being from personal experience. Yet, these tools may still not provide a solution in certain circumstances which a PDF should almost guarantee by the fact that I have yet to see a book split into tons of separate PDF documents although I assume this may exist due to Murphy's Law always applying to my arguments yet I would prefer to assume it is true due to the nature of most PDF's being organized like books and if they are split somewhere like in the Murphy's situation above then it is because:

• A idiot did it.
• It was so large of a bundle of information that it had natural boundaries which would justify having separate PDF books (or numerous ones).

Then there may be situations where you get bundled garbage along with the actual text you are interested in because the HTML hierarchy was part of a site with banners and advertisements or some other situation which is where I hope Murphy's Law will now walk over to my side hopefully.

But through and through the majority of PDF file I have viewed seem to be organized like a book with out the bothersome garbage that has nothing to do with the content. So it does feel nice to have a crisp cleanly printed document or viewable document.

I also like to anti-aliasing that is done in PDF documents which is not present on some web pages. I do think most browsers do not support AA yet?

Brendan wrote: I'm using "xpdf" on Linux, which has horrible performance (in a large document, try holding down the "page-down" key for 5 seconds and see how long it takes for the video to catch up). Mozilla doesn't have this problem.

Let's face it, somebody using Linux deserves everything they get. PDF's don't cause any problems in Windows, and I suspect the same is true of the Mac.

I prefer PDF by the way, and I have got more than 20 lever arch files full of the stuff to prove it. I can't stand clicking links, scrolling down pages, then going back a page clicking another link, only to find what I am looking for not there either. And the index, such as it is, about twenty pages further back up the tree.

Brendan wrote:I'm using "xpdf" on Linux, which has horrible performance (in a large document, try holding down the "page-down" key for 5 seconds and see how long it takes for the video to catch up). Mozilla doesn't have this problem.

On my Ubuntu box, it takes less than half a second for the page to be drawn after 5 seconds of page-down in Intel docs.

mathematician wrote:Let's face it, somebody using Linux deserves everything they get. PDF's don't cause any problems in Windows, and I suspect the same is true of the Mac.

See above, I have no such problems with PDFs on Linux.
That's using evince (Ubuntu's default pdf viewer) though. So perhaps the blame lies with xpdf instead of with Linux?
Unless I just have a much faster system...

Hi,

I'm just wondering if people are comparing different ways of putting content into documents, instead of comparing different file formats...

I agree that:

• Many seperate files can be painful to print (regardless of whether they're PDF or HTML).
  Documents without any indexing can make it hard to find what you're looking for (for both PDF and HTML).
  Badly thought-out documentation is bad (for both PDF and HTML).
  Having some sort of navigation is good (for both PDF and HTML).

Of course all these things can apply to any decent document file format, and have nothing to do with the file format itself.

So, what arguments are there for and against HTML and PDF file formats that are specifically about the file formats, and not about how people choose to arrange their documentation?

From my perspective:

• HTML is much more standard/open, and much easier to work with (for e.g. it took me about a week to write code to auto-generate HTML from assembly source code, while it'd take me several weeks to fully understand the PDF file format), assuming you stick to basic HTML and don't get into Java scripting PHP and other stuff.
  For HTML it's easier to generate several different versions of the same document (e.g. one as "single file", one as "page per chapter", etc), and therefore much easier to have one version suitable for printing and another suitable for online viewing (or downloading for reference).
  For PDF it's much easier to embed pictures (diagrams, etc) into the document so that a single file contains everything.
  PDF supports DRM, which makes it an obvious choice if you want to restrict how people can use your documents.

urxae wrote:

Brendan wrote:I'm using "xpdf" on Linux, which has horrible performance (in a large document, try holding down the "page-down" key for 5 seconds and see how long it takes for the video to catch up). Mozilla doesn't have this problem.

On my Ubuntu box, it takes less than half a second for the page to be drawn after 5 seconds of page-down in Intel docs.

I'd assume it depends on how fast your computer is and how good your PDF viewer is. I'm guessing XPDF is a single-threaded application, while I'm running it on a machine with a pair of 1 GHz Pentium IIIs. For me, the keyboard repeats the "page down" about 5 times faster than XPDF can draw a page, and it can take 30 seconds or more for XPDF to catch up to 5 seconds of key repeats. Anyway, I did an "emerge kpdf" - hopefully that'll help...

mathematician wrote:Let's face it, somebody using Linux deserves everything they get. PDF's don't cause any problems in Windows, and I suspect the same is true of the Mac.

In that case, why not document your project in Microsoft Word format? It's probably got less patents than PDF...

I did do a little research though, and found that PDF has become more "open" than it used to be - out of 7 patents only one of them restricts other developers (and only if they're writing code that reads or converts PDF files - generating PDF files is OK).


Cheers,

Brendan