LinuxQuestions.org
Review your favorite Linux distribution.
Go Back   LinuxQuestions.org > Forums > Non-*NIX Forums > Programming
User Name
Password
Programming This forum is for all programming questions.
The question does not have to be directly related to Linux and any language is fair game.

Notices

Reply
 
Search this Thread
Old 02-13-2008, 12:21 AM   #1
ta0kira
Senior Member
 
Registered: Sep 2004
Distribution: FreeBSD 9.1, Kubuntu 12.10
Posts: 3,078

Rep: Reputation: Disabled
opinion of PDF for C-library documentation


This is one of those posts where I've pretty much decided what I'm going to do anyway, but would like input from other people.

I'm writing documentation for a project I find to be quite complex. I've always run into problems documenting in HTML in the past such as parsing and making it look how I want, not spending enough time on the actual content and flow of the document. I recently decided to switch to PDF using OpenOffice.org Writer and I've come up with 60 pages of amazing (-looking) documentation over the last few days. It looks quite a bit more professional than the HTML I've come up with and it's a whole lot easier to read and to write.

The main drawbacks I see are lack of availability "right there" over the internet and the inability of some programs (such as KPDF and KGhostView) to copy text from the document for pasting into source code. An alternative to that would be to include source code files for examples, but my document currently has endless 4-line snippets to explain things.

As a developer, do you appreciate readability and convenience over quick access over the internet, possibly at the expense of being able to copy and paste? I'm open to other suggestions but I refuse to create another poll. Thanks.
ta0kira
 
Old 02-13-2008, 06:05 PM   #2
jailbait
Guru
 
Registered: Feb 2003
Location: Blue Ridge Mountain
Distribution: Debian Wheezy, Debian Jessie
Posts: 7,474

Rep: Reputation: 155Reputation: 155
Quote:
Originally Posted by ta0kira View Post

As a developer, do you appreciate readability and convenience over quick access over the internet, possibly at the expense of being able to copy and paste? I'm open to other suggestions but I refuse to create another poll.
As a user of documentation I detest pdf. When using Google I always choose "View as HTML" when Google gives me that option for a pdf file.

When I write documentation I first write it as text in a text editor. Then I sometimes transfer it to html. Once a project leader asked me to rewrite some of my documentation from HTML to DocBook XML which Gnome uses as a standard documentation format.

http://tldp.org/LDP/LDP-Author-Guide...dversions.html

I did it and swore that I would never use DocBook XML again. It was extremely slow and tedious. I suppose that I would reconsider if there was a decent DocBook XML editor.

-----------------------
Steve Stites
 
Old 02-13-2008, 07:04 PM   #3
95se
Member
 
Registered: Apr 2002
Location: Windsor, ON, CA
Distribution: Ubuntu
Posts: 740

Rep: Reputation: 32
I've been using latex for most everything over the past year and a half. Produces awesome looking documents, and lets you focus on the content while writing.

EDIT: Creating PDFs from latex files is easy and is what most people use as the presentation format for their tex docs

Last edited by 95se; 02-13-2008 at 07:08 PM.
 
Old 02-13-2008, 07:10 PM   #4
95se
Member
 
Registered: Apr 2002
Location: Windsor, ON, CA
Distribution: Ubuntu
Posts: 740

Rep: Reputation: 32
Quote:
Originally Posted by jailbait View Post
As a user of documentation I detest pdf.
+1. I never just look at 1 page in documentation, but usually have 5+ different tabs in my browser open. PDF just isn't good for random access (by a human, that is), but HTML is pretty good.

However, when I plan on reading the majority of some documenation (more like a reading a book), I usually print it off, and PDF stuff just does better for that... since WYSIWYG on the printer.

Last edited by 95se; 02-13-2008 at 07:12 PM.
 
Old 02-13-2008, 07:26 PM   #5
jschiwal
Guru
 
Registered: Aug 2001
Location: Fargo, ND
Distribution: SuSE AMD64
Posts: 15,733

Rep: Reputation: 654Reputation: 654Reputation: 654Reputation: 654Reputation: 654Reputation: 654
An original format like docbook while maybe harder to write for initially will allow either html or pdf documents or info files to be produced.

I'll often download source code for a package and produce the pdf version of the manual or book from the texi source used to produce the info files. One example is "GAWK: Effective Awk Programming" which I produced the pdf version and then printed that off.

HTML sucks for printing. PDF file based documentation is easier to download from a website. If you are careful in not using funky fonts and formatting, cutting and pasting from pdf files is not a problem. However if you produce a pdf document by printing to a pdf file that may produce a poor pdf file, almost as bad as a fax image. I hate trying to read a pdf document where the diagrams are over compressed jpeg files instead of drawings that you can zoom in on.
 
Old 02-13-2008, 10:23 PM   #6
ta0kira
Senior Member
 
Registered: Sep 2004
Distribution: FreeBSD 9.1, Kubuntu 12.10
Posts: 3,078

Original Poster
Rep: Reputation: Disabled
I agree with everything that's been said, but I think I should have explained what I'm doing a little bit more.

The document I'm currently working on is really 2 user's guides in one. The first is for administrators of the system who needn't have any programming experience, but need to know how to use a shell. The second is for extension developers, but it's mainly just a quickstart so they know what in general needs to happen to create extensions, as well as a few key headers and functions.

I have a section at the very end of the current document reserved for the API reference. I've been ignoring it because I know it won't work in a PDF file. I think something mentioned above will be more suitable, probably with the help of DOxygen.

The administrator's and extension developer's quickstart guides cover fairly abstract information that's necessary in order to understand the project well enough to perform either function. I think I intend both to be used as an intro to the project (well, currently 74 pages worth) and then as a quick reference when an administrator or developer need a reminder about the internal functionality of the system. I've avoided as much actual code in the document as possible, but will probably create a "usable" API reference and manpages for the shell commands.

So I guess I've decided to go with man/info for the shell commands and something in line with the comments above (which I haven't decided on) for the API, but I do think I need a colorful, graphical, highly-formatted intro document for both administrators and developers. I've already ruled out HTML and Latex because of the "highly-formatted" requirement. Are there any other document formats that allow images, diagrams, tabs, colored/shaded text with borders, hyperlinks, etc. that actually show up as I've written them for everyone? Thanks.
ta0kira

PS The reason I want the intro guide(s) to look extremely professional is this is a fairly complex system that requires quite a bit of effort to understand well enough to use, and even more to develop for. I'd rather people not discard it before knowing what it's capable of because the document came out either too primitive-looking or misaligned.

PPS Sadly, the project is actually a "facility" that does nothing dazzling on its own. It will require the help of outside developers to create useful extensions for it to create large-scale modular applications. I will probably have to create a showy system of my own extensions to get peoples' attention, but that's an entirely different issue...

Last edited by ta0kira; 02-13-2008 at 10:35 PM.
 
Old 02-14-2008, 06:33 AM   #7
AnanthaP
Member
 
Registered: Jul 2004
Location: Chennai, India
Distribution: UBUNTU 5.10 since Jul-18,2006 on Intel 820 DC
Posts: 607

Rep: Reputation: 127Reputation: 127
pdf is still proprietarily created by adobe and their later version may not be supported by linux distributions.

So while you may have no problem, I would go with HTML every time.

Also, pdf does'nt always read well - particularly when it is created by some publisher who might put 2 columns across some arbitrarily (for the end user) decided page size. An A4 print sheet does'nt for instance render well on a screen. User would have to keep scrolling back and forth and so on.

End
 
Old 02-25-2008, 05:43 PM   #8
ta0kira
Senior Member
 
Registered: Sep 2004
Distribution: FreeBSD 9.1, Kubuntu 12.10
Posts: 3,078

Original Poster
Rep: Reputation: Disabled
Well, here's the status. The PDF thing was great for getting the ideas out of my head, but now I don't even like updating it. Here's the plan.

I finally got around to figuring out the deal with CSS and that + XHTML is exactly what I need. It pretty much does exactly what I asked for in a previous post in this thread, but I've been editing the docs with BlueFish instead of a "WYSIWYG." I don't mind hand-writing it, and the built-in CSS and HTML guides are a huge help.

I'm going to use the above for the overview and guides and I found a DOxygen Eclipse plug-in for the API documentation. I'd never used DOxygen for C documents, but it's a whole lot less painful than using it for C++!

The project should be up and running with docs in no time. I just need a slow weekend where I can sit down and hammer out at least 2 of the 4 guides I need to write. Here's a link for now:
Resourcerver

Thanks!
ta0kira
 
Old 04-23-2008, 11:16 AM   #9
archtoad6
Senior Member
 
Registered: Oct 2004
Location: Houston, TX (usa)
Distribution: MEPIS, Debian, Knoppix,
Posts: 4,727
Blog Entries: 15

Rep: Reputation: 230Reputation: 230Reputation: 230
Thumbs up

Sorry to seem like a Johnny-come-lately, but I just stumbled over this.

Glad you found a way to use HTML -- I detest PDF for documentation. My biggest bitch is that I can't zoom the display to a size that is good for my old eyes & have it stay w/in the edges of my screen. Konqueror, my default browser, can usually do this; & Opera is superb at dealing w/ the most recalcitrant cases.

BTW, please try to provide a single page ver., rather than a multi-page only -- it really facilitates searching the whole document.
 
  


Reply


Thread Tools Search this Thread
Search this Thread:

Advanced Search

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is Off
HTML code is Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
pdf copy of apache 1.3.34 documentation ic_torres Slackware 1 03-26-2006 03:40 PM
C library documentation arunswarup Solaris / OpenSolaris 7 10-17-2005 03:56 PM
apache2 documentation in pdf? Harry Seldon Linux - Newbie 6 08-24-2005 08:48 AM
Standard C and C++ Library Documentation elluva Programming 12 10-25-2004 04:28 AM
documentation in PDF Elbolton Linux - Newbie 3 02-17-2002 10:19 AM


All times are GMT -5. The time now is 12:47 PM.

Main Menu
My LQ
Write for LQ
LinuxQuestions.org is looking for people interested in writing Editorials, Articles, Reviews, and more. If you'd like to contribute content, let us know.
Main Menu
Syndicate
RSS1  Latest Threads
RSS1  LQ News
Twitter: @linuxquestions
identi.ca: @linuxquestions
Facebook: linuxquestions Google+: linuxquestions
Open Source Consulting | Domain Registration