Documentation "containers"

[Don Y]

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!

 

[Tim Williams]

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

 

[miso]

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

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.

 

[Don Y]

Hi Tim,

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...

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?

 

[Don Y]

Hi David,

On 13/04/2012 05:51, Don Y wrote:

I think pdf is the only commonly used document format that supports
things like animations as well.

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

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).

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).

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.

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.

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

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).

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.

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

 

[SoothSayer]

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.

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

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 :> )

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* PDF is the only appropriate container, my next question
is: "What aspects should I *avoid* to increase support for
non-Adobe viewers?"

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.

(I'm really only interested in mainstream
tools...

Adobe PDF.

not something obscure that "looks promising", etc.)

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.

 

[TheQuickBrownFox]

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.

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.

 

[Jasen Betts]

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 :> )

odf perhaps?

or just a collection of HTML and media files?

*If* PDF is the only appropriate container, my next question
is: "What aspects should I *avoid* to increase support for
non-Adobe viewers?"

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

 

[Jasen Betts]

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

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.

 

[Jasen Betts]

Hi Tim,



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?

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

 

[Don Y]

Hi David,

On 4/13/2012 5:22 AM, David Brown wrote:

[elided]

That's maybe okay if the multimedia is quite small, and tightly tied to
the documentation.

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.

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.

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!)

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.

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.)

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.

I'll look at what's out there.

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.

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

If /you/ have to buy particular software, then I
expect it would be a small matter overall.

Agreed. Even if its not so "small"

Google for "pdfLaTeX multimedia" if you like.
OK.

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.

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!)

 

[Don Y]

Hi Jasen,

odf perhaps?

I suspect that already significantly limits the viewership.

or just a collection of HTML and media files?


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

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

<frown> 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.

 

[Don Y]

Hi Robert,

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.

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).

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.

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!)

 

[Martin Riddle]

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!

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

 

[Don Y]

Hi Martin,

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

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

Otherwise PDF, but avoid FORMS as foxit does not understand some of
adobe features.

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

We use PDF, and everyone has Adobe reader. Adobe Standard is good enough
to create 99% of the documents.

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

 

[miso]

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.

Ah, it appears shit for brains is "always wrong" again.

You do realize the embedded video would have to be flash. People hate
flash nearly as much as they hate shit for brains assholes like you.

 

[Oliver Betz]

David Brown wrote:

[...]

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

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.

[...]

The best way to make pdf's is using programs that support them directly.
For normal word-processor files, use LibreOffice (or OpenOffice). If

Maybe I'm not able to get the right settings, but these always
produced _much_ larger PDF documents than GhostWord
http://ghostword.sourceforge.net/ (seemingly no more maintained)

you are interested in making high quality documents, use pdfLaTex. If

Hmm...

Oliver

 

[tim....]

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.

Surely the "point" of PDF is that the user can decide how much scrolling he
wants to do by choosing a "page size" zoom for himself.

Boy do I hate implementers who make this decision for me and then wont let
me change it!!!!!!!!!!!!

 

[WoolyBully]

good.

Well, from a Usenet POV, you are a total retard.

 

[WoolyBully]

Surely the "point" of PDF is that the user can decide how much scrolling he
wants to do by choosing a "page size" zoom for himself.

Boy do I hate implementers who make this decision for me and then wont let
me change it!!!!!!!!!!!!

You ain't real bright, and your common sense and logic faculty is
severely lacking. The reason for PDF is so that the PAGE IMAGE will look
the same no matter what the user views it with. It has a specific,
targeted purpose, you dopey ****.

THAT was the original idea.

NOTHING you come up with matches what they did things for, nor what
things are done for now.

Then, your stupidity is culminated by the use of far too many
exclamation points.