Documentation "containers"

Hi,

I'm releasing documentation packages for several designs and am interested in *alternative* containers besides ".PDF". I want a self-contained document -- not a hole slew of files linked together, etc.

I would like to tie in text (d'uh) photos/illustrations, animations, sound and video. (obviously, the "documents" don't render well in pen-and-ink :> )

*If* PDF is the only appropriate container, my next question is: "What aspects should I *avoid* to increase support for non-Adobe viewers?" (I'm really only interested in mainstream tools... not something obscure that "looks promising", etc.)

Thanks!

Reply to
Don Y
Loading thread data ...

HTML / XML, optionally generated live from scripts, DB, etc.

There's always LaTeX, you can compile a PDF from sources with little more than scripting. Perhaps a bit less pretty than perl...

Tim

--
Deep Friar: a very philosophical monk.
Website: http://webpages.charter.net/dawill/tmoranwms
 Click to see the full signature
Reply to
Tim Williams

HTML is a good idea. Everyone has a browser. You can use Komposer or some similar free program to generate the document. Potentially not every use would have a video plugin.

Customers trust pdfs because they think (falsely of course) that the file can't harm their system, while some customers might do a Spock raised eyebrow if they receive html.

Reply to
miso

I think pdf is the only commonly used document format that supports things like animations as well. If you don't want to put them in a pdf file, I'd suggest a zip file. Actually, I'd suggest a zip file anyway - I think it is better to stick to plain "pen-and-ink" for the pdf file, and put any multi-media stuff in separate files (packaged within a single zip if you like).

As for making and checking standard pdf formats, the biggest step is to avoid Adobe. No one who thinks about these things ever uses Acrobat Reader for viewing files - in comparison to alternatives like Foxit and Evince, Acrobat is astonishingly bad bug-ridden bloatware of the worst kind. And avoid Adobe products for generating pdf files - they are big, expensive, generate poorer quality pdf files than many alternative methods, and sometimes make pdf's that have problems with anything but the latest version of Acrobat Reader.

The best way to make pdf's is using programs that support them directly. For normal word-processor files, use LibreOffice (or OpenOffice). If you are interested in making high quality documents, use pdfLaTex. If you want careful control of page layout, use Scribus. These are all open source, cross-platform tools and give the best quality pdf files (things like tables of contents, indexes, clickable cross-references, etc.). The also make pdf files that always work. If you need a "printer" style pdf generator, go for pdfCreator (or cups pdf printer on Linux) - again it's free, and works well.

Reply to
David Brown

Note: "I want a self-contained document -- not a whole slew of files linked together, etc."

I don't see HTML or XML (etc) as providing this. Or, is there some capability I am overlooking?

Reply to
Don Y

That's what my initial research seemed to suggest...

I've tried using a browser-oriented approach -- a folder full of files referenced in a "controlling document". It's clumsy. And, too easy for pieces to get misplaced/corrupted/etc. E.g., if you're reading text describing how the speech synthesizer works, you want to *hear* the particular sounds being generated and

*see* the imagery showing how the vowel (and consonant) sounds "move" around your vocal tract. Trying to convey this sort of information in text and still images just doesn't cut it...

There are some legacy products that can do what I want -- but, support for them (or their file formats) is pretty slim (obsolescent).

Do the alternatives offer the same range of multimedia support? Or, am I stuck with "text/graphics"? (unacceptable)

I'd also like to be able to allow users to *extract* portions of the (unprotected) document as necessary. E.g., artwork for PCB layouts.

I don't care if the tool is open source or commercial. I care about preparing a document that fits my goals -- and, the consequences for other "non-Adobe" products that may or may not be up to the task of presenting that document AS INTENDED (which is the whole purpose of PDF's).

I don't see how they are going to address the multimedia issues (?)

Reply to
Don Y

PDF IS the standard. Step outside the accepted norms at your own risk.

PDF IS the standard. It guarantees that the viewer of your document will see it the way YOU format it, regardless of what he or she uses to view it. There are very few, if ANY other document management packages that can offer that.

IF they want to examine your documents, they WILL be using a PDF viewer of some kind. No need to worry, if the viewer is a compliant one. Most are, or they die.

Adobe PDF.

Do not try to make it something obscure then. Adobe PDF is the standard, short of making presentation pages which are hard graphic images. You would have to embed link areas on such a page, manually.

Reply to
SoothSayer

Idiot. The reason PDF is used is because your web page suggestion would virtually guarantee that every viewer would see a different page, based on their own personal browser settings and 'page size' of the browser window.

A PDF means that ALL users will see EXACTLY the same page.

Your guesses as to why a user examines a page based on its format are as stupid as your grasp of why it is really done.

Reply to
TheQuickBrownFox

That's maybe okay if the multimedia is quite small, and tightly tied to the documentation. But if it makes the pdf documentation much bigger, then personally I would prefer the pdf file to be separate.

I haven't actually tried anything like this to tell. The nearest I have come is using pdfLaTeX with attached files (program code) - that certainly worked without problem, and the program file can be saved separately from the pdf file.

But I /have/ seen Adobe's software making a complete hash of generating pdf files, such as making pdf's that are orders of magnitude bigger than necessary, or that only work on some computers or some readers.

Fair enough. But when giving suggestions for things to try, I don't think it is appropriate to recommend commercial software unless I know for sure that it is up to the job (and in this case, I don't know of any). With free software (which I know to be good quality, and /really/ free - not adware, trialware, etc.), then I can suggest you try it out and see. Maybe it will do the job, maybe not - but at least you haven't wasted lots of money on it.

The key point, of course, is that the results should be accessible to anyone without having to buy additional software or be tied to a particular platform. If /you/ have to buy particular software, then I expect it would be a small matter overall.

Google for "pdfLaTeX multimedia" if you like.

As far as I understand it, you want to generate professional-looking pdf files - and that means you need to have these features. A great many pdf files - even those made with Acrobat - fail in this way.

Reply to
David Brown

odf perhaps?

or just a collection of HTML and media files?

Animation, sound, video. and anything else that relies on javascript in the PDF.

--
?? 100% natural

--- Posted via news://freenews.netfront.net/ - Complaints to news@netfront.net
Reply to
Jasen Betts

if it's done right it does, if it uses some font that's not embedded correctly results can be highly variable.

I've seen plenty of PDFs that give three different results with three different readers.

--
?? 100% natural

--- Posted via news://freenews.netfront.net/ - Complaints to news@netfront.net
Reply to
Jasen Betts

inline data ("data:" urls), AIUI not supported by IE , possibly not supported by many plugins either. only works with tree structures

--
?? 100% natural

--- Posted via news://freenews.netfront.net/ - Complaints to news@netfront.net
Reply to
Jasen Betts

-

The only application area I can think of off hand that uses this regularly would be education. You might want to check with Universities and see what their remote education arms use.

The one application I can think of that would do this is (Ugh!) Flash. You might even be able to find appropriate authoring tools. As a consumer I'd howl and complain if that was the documentation format but other than perhaps authoring, I think it meets your requirements.

Robert

Reply to
Robert Adsett
[elided]

Yes. I'm not intending to include "how to videos" or lengthy audio excerpts. Rather, things like:

- this is what the vocal tract looks like AS this sound is made

- this is how a 2D curve changes over time under this influence etc.

Things where you want to consult the text *as* you are viewing/hearing the presentation. And, be able to easily replay it, etc.

I know I can extract photos embedded within PDF's. Not sure what the "free" tools can do.

(I've also learned to *crop* photos before inclusion into the PDF since cropping them *in* the file still leaves the cropped portions available when the photo *is* extracted!)

I've never noticed a big difference between file sizes regardless of how the file was created -- but, that's been just text+images, up to this point. I recall options to specify the PDF "level" to generate the output format.

And, I've avoided the "non-Adobe" readers simply because everyone

*can* get Adobe's version without a financial commitment (and I don't want to be dealing with XYZreader on BozoOS not being able to read my documents, etc.)

I'll look at what's out there.

Yes. Though not as dogma (if you can't view the documents on BeOS you won't get much sympathy from me! :> )

Agreed. Even if its not so "small"

OK.

I'm very good at generating content. What I need is to make sure the content that I want to present to the user is accessible to him/her -- without having them jump through hoops.

(documentation is supposed to make things *easier*, not harder!)

Reply to
Don Y

I suspect that already significantly limits the viewership.

Ouch! Why not just type things up using a Selectric typewriter and take TIFFs of the resulting pages??

If it's really *that* bad for the non-Adobe readers, I suspect that means Adobe gets the job. :<

Too many things are just too hard to explain with words and still images. E.g., I can use IPA to describe a pronunciation -- and most folks will gloss right over it! Or, I can verbosely describe how different vowel sounds are "regionalized" (USA) and, unless you are familiar with those "regional accents", you'd never be able to relate the description to the actual

*sound*. Or, let you twiddle with parameters and see how a particular curve responds.
Reply to
Don Y

Ah! Good idea! I will ask a neighbor who had an online "education" firm to see what the software that he used entailed. IIRC, it was lots of flash animations (geared to children, not "adults"). I recall it was a real *pig* in terms of the hardware required to run it effectively (I think it was all scripted).

I'm not sure Flash would relate well to the "traditional content". I.e., imagine reading a flash-based newspaper/magazine. You want to see a page and zoom/pan to parts of the page to explore the content -- not be glued to a "presentation frame".

(I also philosophically object to Flash -- it's not installed on *this* machine!)

Reply to
Don Y

Only if they want to: Almost all PDF readers designed for tablets and smartphones will attempt to re-flow the text to deal with the (typically) smaller screens so that the user doesn't have to scroll as much. Indeed, I believe that newer versions of the PDF spec allow specifically for the inclusion of mark-up "hints" so that re-flowing will look a bit better.

Reply to
Joel Koltner

Multipage Tiff. If you can find a viewer that handles multipage tiff.

Otherwise PDF, but avoid FORMS as foxit does not understand some of adobe features. We use PDF, and everyone has Adobe reader. Adobe Standard is good enough to create 99% of the documents.

Cheers

Reply to
Martin Riddle

Doesn't handle multimedia. (And, TIFFs are bigger than rendered text would be)

It seems that you need Adobe to get all the "advanced features" as the clones seem to be not quite up to the task... :<

I've never had a problem in the past with text+images documents. But, going beyond that is where my current interests lie.

Reply to
Don Y
[...]

As far as I see, Foxit tries hard to catch up with Adobe in this regard. I remember Foxit bringing more critical bugs per month than Adobe.

Currently I'm evaluating Sumatra PDF.

[...]

Maybe I'm not able to get the right settings, but these always produced _much_ larger PDF documents than GhostWord

formatting link
(seemingly no more maintained)

Hmm...

Oliver

--
Oliver Betz, Munich (oliverbetz.de)
Reply to
Oliver Betz

ElectronDepot website is not affiliated with any of the manufacturers or service providers discussed here. All logos and trade names are the property of their respective owners.