Connect with us

Documentation "containers"

Discussion in 'Electronic Design' started by Don Y, Apr 13, 2012.

Scroll to continue with content
  1. Don Y

    Don Y Guest


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

  2. Tim Williams

    Tim Williams Guest

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

  3. miso

    miso Guest

    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.
  4. Don Y

    Don Y Guest

    Hi Tim,

    "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?
  5. Don Y

    Don Y Guest

    Hi David,

    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 (?)
  6. SoothSayer

    SoothSayer Guest

    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.
  7. 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.
  8. Jasen Betts

    Jasen Betts Guest

    odf perhaps?

    or just a collection of HTML and media files?

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

    Jasen Betts Guest

    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.
  10. Jasen Betts

    Jasen Betts Guest

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

    Don Y Guest

    Hi David,

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

    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

    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"
    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!)
  12. Don Y

    Don Y Guest

    Hi Jasen,

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

    <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.
  13. Don Y

    Don Y Guest

    Hi Robert,

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

  15. Don Y

    Don Y Guest

    Hi Martin,

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

    miso Guest

    Idiot. The reason PDF is used is because your web page suggestion
    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.
  17. Oliver Betz

    Oliver Betz Guest

    David Brown wrote:

    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

    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 (seemingly no more maintained)

  18. tim....

    tim.... Guest

    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!!!!!!!!!!!!
  19. WoolyBully

    WoolyBully Guest

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

    WoolyBully Guest

    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.
Ask a Question
Want to reply to this thread or ask your own question?
You'll need to choose a username for the site, which only take a couple of moments (here). After that, you can post your question and our members will help you out.
Electronics Point Logo
Continue to site
Quote of the day