Documentation "containers"

[Don Y]

Half-groggy here, but if I understand your question, check out some
lesson authoring tools such as SoftChalk.
www.softchalk.com

I know.... the knee jerk reaction is that it won't seem like the right
solution.
But SoftChalk has a capability to encapsulate an entire HTML-based
"lesson" as an executable file (Windows or OS X).

*Executable*? Meaning it is tied to a particular OS (can I "view"

So, you can distribute a tremendous wealth of information (text,
video, interactive stuff, etc...) all at once, anywhere you like: on
the web, CD, zip, executable, etc...
Done right, this can be very, very powerful.
I suppose you could even create an interactive product registration
function.

Not concerned with getting information *back* from people.
Rather, showing them how to use and modify hardware and software
that is described by the documents. As well as explaining how
the stuff actually works, why certain design decisions were
made, etc.

I use SoftChalk all the time for weird stuff because it's so damn easy
to use (and they don't pay me to say that).
I don't recall it being particularly easy on the wallet, however - so
that may be a consideration.

If the cost is only seen by the *developer* (no run-time costs),
that's not a problem. Many of the tools I use have hefty pricetags.

I think they offer a free trial on their web site, so why not take a
test drive to see if it will work for your needs.

I'll build another (disposable) machine and see what it looks like.
The "tied to OS" aspect is a big downside, though.

There are other lesson authoring tools out there that may work as well
or better, but I'm jnot familiar with them.

I spoke with a neighbor who had a business doing this sort of thing.
But, he claimed the "lessons" were more like something you would
see on a 21st century "blackboard"/slideshow than in a 21st century
"technical paper". I.e., "short on text".

Imagine a "paper" explaining different sorting algorithms (shell,
quick, insertion, bubble, etc.) -- to someone who knows nothing
about sorting or how prevalent it is. I.e., a slideshow with the
typical dearth of printed commentary would hardly be effective.
OTOH, a long, verbose description of each algorithm and analysis
of pseudocode would swamp the reader in detail. However, add to
that detail some simple animations showing how an unsorted list is
examined by each algorithm and the incremental changes that each
algorithm makes to the list and you can add lots of value to the
presentation.

Or, imagine illustrating different amplifier topologies (A, AB, D,
etc.). If you can *show* where power is being dissipated as a
function of time, then the efficiencies of the various designs
become more apparent than just computations on the page.

Or, how different control technologies (bang-bang, PID, SPC, etc.)
interact with the plant. The roles of deadband, hysteresis, etc.
Whether the control improves or worsens the process, etc.

Now, imagine the "reader" being able to go back and *interact*
with each of the examples you've presented. I.e., put the
items in the initial list in a particular "pathological" order
prior to running a "sort"; driving the input to an amplifier
to a particular *DC* point to study the "static" conditions in
the circuit; altering the transport delay of the output (or
sense) variable in the process; etc. "What if".

(What do these phonetic rules indicate the letter sequence
"slitoeglsdfg" is likely to sound like? When is "ghoti"
likely to be a fish??)

I.e., the document can answer questions that the reader poses
instead of just those questions that the writer considered!

 

[miso]

It is always best to avoid adobe products. Those people can't code.
Seriously, they suck. Unfortunately, Adobe owns a few markets.

 

[Don Y]

It is always best to avoid adobe products. Those people can't code.
Seriously, they suck. Unfortunately, Adobe owns a few markets.

That hasn;t been my experience. I'd sooner give up gcc than, for
example, FrameMaker! :<

 

[UltimatePatriot]

It is always best to avoid adobe products.

You're an idiot.

Those people

Some 'Ross Perot' like stupidity oozes from you as well. Good job,
dipshit. I say you have Zimmerman Complex Disorder.

can't code.

A retarded twit like you wouldn't know, as I will prove shortly.

Seriously,

Seriously, retarded twits like you need your ass kicked by company
owners such as that of Adobe.

they suck.

You suck. That is a fact, and this post is yet one more proof.

Unfortunately, Adobe owns a few markets.

Must mean they know how to code then, you stupid fucktard!

 

[Fred Abse]

It guarantees that the viewer of your document
will see it the way YOU format it

Provided that you embed any uncommon or oddball fonts.

 

[SoothSayer]

Provided that you embed any uncommon or oddball fonts.

I essentially was referring to the basic and original design paradigm
for pdf.

What it currently is makes for two views.

One, with all requisite embedding, which will appear exactly the same
on every machine.

The second, without embeddings, ends up being a graphic backdrop with
pasted areas, and can appear differently on different machines, as the
pastes move around a bit.

It is weird that some of our guys design on a "D" sized 'sheet', which
allows one to print on A, B or legal sized stock, and get a nice print
job. Print on D if it really is a lot of info, but on the smaller stocks
for things you would normally expect to be on such size sheets. It works
out really well.

Authored correctly, which is a simple pre-requisite, and should be for
anything, they follow the rule of their original design plan. This is
the reason, BTW, our industry (electronics) embraced them. Presentations,
manuals, test reports, drawings, etc. could all be distributed reliably
and quickly with high confidence in repeatability.

Our government used to be that way too. Sad that I find myself
laughing at that, when none of us should be.

 

[Jasen Betts]

Some 'Ross Perot' like stupidity oozes from you as well. Good job,
dipshit. I say you have Zimmerman Complex Disorder.


A retarded twit like you wouldn't know, as I will prove shortly.


Seriously, retarded twits like you need your ass kicked by company
owners such as that of Adobe.

let's hear if for the free market!

Must mean they know how to code then, you stupid fucktard!

means they don't need to produce quality.

 

[josephkk]

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!

I wonder if SGML has been (or has needed to be) extended to support
multimedia content? Of course i don't know of SGML readers either.

While HTML can be done monolithically it was not intended to be used that
way.

?-)

 

[Don Y]

Hi Robert,

Actually, I vaguely recall seeing something similar to PDF
presentation within flash.

Hmmm... I will have to look into that. I can't see how it
would be "usable", though (lack of imagination on my part?)

Likewise.

Yup. I feel I'm not missing much (besides *ads* and stoopit
cat tricks).

Though I dug out a pair of these:
http://www.snotmonkey.com/work/ezgo/
last night with the intent of installing a minimal system on
each that I can quickly/easily restore (i.e., in minutes instead
of hours) so I can use them + sneakernet for those few things that
I might want to evaluate *without* compromising a "real" computer.

Amusing little devices but the active cooler is just too damn loud!
I'm hesitant to do anything about it as they run 2.4G processors
and I don't want to *melt* one while evaluating how quiet I *might*
be able to get the cooler. :<

[and the slew of connectors makes it damn near impossible to use
all of them and still be able to get your *fingers* in to grasp
each cable!!]

Gotta wonder what the Marketing Directives were when designing
these beasts! "Here's a 5 pound bag. Let's start at 12 pounds
and work our way *up*!"

 

[josephkk]

Flash is occasionally useful - there are a some sites that have
interesting content or products which can't be navigated without it, or
have video clips, animations, etc., which are worth seeing. I find the
best compromise is to use Firefox or Chrome/Chromium with "flashblock".
That way any flash element is just a box with a "play" icon in it - I
only see the flashes that I choose to see. Along with "adblock plus",
it makes web browsing vastly more pleasant.


Why not simply download VirtualBox and make virtual machines for
testing? It's free, far faster, lets you do snapshots, clones, and
restores easily, and saves you finding space for a new screen and keyboard.

I use NoScript in Firefox which is a little more general. Thus i get to
know just how many ill done sites cannot survive without scripts (it is a
LOT). I couple that with Ghostery (blocks trackers) and on some computers
TACO. I am also terribly anal about limiting cookies, none survive the
session.

?-)

 

[Don Y]

Hi David,

Why not simply download VirtualBox and make virtual machines for

I've always been disappointed with emulations. There's always
*something* that they don't emulate properly. (The folks at Sun
understood this ages ago with their SunPCi products... cheaper
to just provide the extra hardware in *case* it is needed!)

With a small box of *real* hardware, I can install a driver for
a device that I want to test and *know* that any "problems" are
the fault of the actual driver -- not an emulation environment
that's not quite up to par, a configuration parameter that
needs to be tweaked, etc. Part of the appeal of these little
machines is the abundance of I/O's: 4xUSB, 2xEthernet, TVout,
SPDIF, VGA, S-Video, 2xFW, 2xPS2, PCMCIA, serial, parallel,
line in/out, headphone/mic. And, I can carry it to wherever
I *need* it (instead of carrying whatever *else* to some
particular machine!)

testing? It's free, far faster, lets you do snapshots, clones, and
restores easily, and saves you finding space for a new screen and keyboard.

Don't have to *add* a screen/keyboard. Just plug into one of
the existing screens/keyboards. I think we have 14 or 15 monitors
(not counting digital capable TV's) currently deployed around the
house -- most with A/B/C/D switches so "supporting" a hand-sized PC
just entails leaving a video cable plugged into one of the unused
inputs on the monitor.

I think a "basic" OS installation is probably small enough
to fit a compressed image on a DVD so I should be able to
make a self-restoring DVD (and use it for *both* of these
devices). So, if I ever "suspect" the system is wonky,
I can restore a complete image in less than 10 minutes
and start over!

 

[Don Y]

Hi Joseph,

I use NoScript in Firefox which is a little more general. Thus i get to

Agreed. However, I wish NoScript would let you configure which
"script domains" to allow on a per-site basis. I am reluctant to enable
particular domains unilaterally so end up having to experiment on
a site-by-site basis: does this site *really* need googleapis?
I'm pretty sure it *doesn't* need facebook... etc.

know just how many ill done sites cannot survive without scripts (it is a

Sad to see how much is now done *in* scripts that needn't be.
Sort of like they've forgotten how to ride a bicycle because they've
been spoiled with driving *cars* all this time...

 

[Don Y]

Hi David,

Well, obviously it's up to you. For some things, such as drivers or
demanding graphics, you need to work with a real machine and not a
virtual machine (except usb drivers - these almost always work fine in a
virtual machine, at least with a Linux host). But other than that you
are wasting time and money. Virtual machines these days are solid
systems, not some sort of experimental toy. My understanding is that you
wanted to test different installations, different combinations of
document readers, different settings, etc., without risking your main
working machine - that is a perfect task for virtual machines.

No:
"... so I can use them + sneakernet for those few things that
I might want to evaluate *without* compromising a "real" computer."

Windows is a silly OS when it comes to installing software.
First, it requires more privilege than it *should*. Second,
it entwines itself in far too many system objects (libraries,
registry, special places in the file system, etc.). Third,
it hides damn near all of the modifications that it has
made to the system. Fourth, it is rarely *completely*
reversible. Fifth, the sum of these give you no assurances
that it hasn't *broken* something that was working previously.

E.g., I want to test a "display calibrator" (photocell on a USB)
and I have no idea if that will break something -- possibly
completely unrelated to its *presumed* functionality. And, if
I then decide NOT to use the device, I have no way of ensuring
that it is removed from my system completely -- and, can't
"accidentally" be reinstalled (accidentally double click on
something and you have no way of knowing what the executable
has *done* BEFORE it asks you if you want to continue, etc.)

A small, "capable" hardware box that I can quickly restore to
a known configuration (*offline* DVD's don't "accidentally" get
overwritten) is one way to ensure that I always have a known
configuration that I can quickly return to.

I have ~10 or 12 virtual machines running on the SunPCi2. I use
them so INfrequently that I have to leave myself detailed notes
about what each is configured to support, any special usage
caveats, etc. I.e., there is a real cost to maintaining them.

Machines are so cheap that it is almost silly (IMO) to emulate
one when you could have a *real* one that actually works *while*
the would-be emulation host is (entirely) used for something else.
Physical space is the only downside. Hence the appeal of
these little buggers... (8 of them side by side would take
up less space than one of my monitors!)

 

[Don Y]

Hi Peter,

I just bought a book-on-CD that is a single .pdf file containing text,
graphics, and several short videos. The book is "Woodworker's Guide
to Sketchup 7" by Bob Lang ( http://craftsmanplans.com/ ). You might
want to discuss this with Bob.

Exactly! I looked at the sample on his site. But, was disappointed
that Reader wanted to download a "media player" in order to let me
view the animation/video. I.e., if you are NOT connected to the
'net and *haven't* previously downloaded the player, you're SoL?

(perhaps it requires a newer version of Reader -- I will have to
investigate).

Bob claims his book can only be fully enjoyed with Adobe Reader, but
it seems to work fine in Foxit Reader, for me.

Neglecting the technical issues, how do you find this "experience"?
Does the presence of the "dynamic content" enhance the ability of
the author to explain/clarify his points? Or, is it window dressing?

 

[Boo]

Machines are so cheap that it is almost silly (IMO) to emulate

one when you could have a *real* one that actually works *while*
the would-be emulation host is (entirely) used for something else.
Physical space is the only downside. Hence the appeal of
these little buggers... (8 of them side by side would take
up less space than one of my monitors!)

It's your money but fwiw I'm in agreement with David : virtual machines work so
well for new and experimental software installations that I wouldn't be without
them. The idea of "re-flashing" a pc each time I want to use a piece of
software or alternatively sorting out a specific box, digging out the cables and
pissing about with hardware seems daft to me. VMs have the further advantage
that they can be exported and used on eg a client site without having hardware
bumping around in the boot of the car.

But hey-ho, each to his own

Boo

 

[Don Y]

It's your money but fwiw I'm in agreement with David : virtual machines
work so well for new and experimental software installations that I
wouldn't be without them. The idea of "re-flashing" a pc each time I

Insert DVD. Boot. Wait 10 minutes while the original disk image
is restored *if* you don't want to worry about the current contents
of that disk (i.e., if whatever you installed/evaluated last time
was "relatively benign" -- text editor, image processing suite,
etc. -- you could opt to just leave it in place until you have a *real*
need to restore the "virgin" state of the machine).

[N.B. I already do this with each machine as it makes reinstalls
painless AND safeguards against "updates" going missing]

want to use a piece of software or alternatively sorting out a specific
box, digging out the cables and pissing about with hardware seems daft
to me. VMs have the further advantage that they can be exported and used
on eg a client site without having hardware bumping around in the boot
of the car.

Are you claiming that the host OS/filesystem will experience *no*
changes outside of those *within* the guest OS's virtual disk
contents when I insert a PCMCIA card, USB device, FW device, PCI
cards, etc.?

And, that the guest OS will be able to *effectively* use each of
these bits of hardware?

Perhaps the *first* use for these little boxes is to install
VirtualBox, VMware, etc. *there* and prove/disprove this claim...

 

[Don Y]

Hi Peter,

The Intro/Installation section describes how to tell Acrobat to use an
available media player, if it doesn't pick one automatically.

I see. Apparently Reader offloads the decoding of the video
to something *outside* Reader itself.

<frown>

This means the user can't *just* have Reader (the latest/greatest)
installed to view the entire presentation. It's the equivalent
of requiring the user to have all of the fonts you've used
already installed on his machine to view a (static) document
correctly.

Sort of like a kid getting a gift and discovering it also
needs *batteries* (which, of course, were carelessly NOT
supplied WITH the gift!). Kind of takes some of the enthusiasm
out of his receiving it...

I will have to see if there is an equivalent way of "embedding"
the decoder in the PDF. Or, consider using simpler animations
instead of full-fledged "videos".

I've only had the CD for a couple of days, and have only browsed
through it, so can't make a fair review. However, I think the videos
will be useful, particularly for someone new to CAD-like programs.
Seeing him actually use some of the Sketchup tools can clarify the
text descriptions.

Yes, that was what I decided when opting to go beyond a "static"
(print) document. It made authoring the text portions of the document
considerably easier when I didn't have to worry about how to
*exactly* explain how something moved, or what something sounded like,
etc.

I'm very familiar with Protel/Altium, and frequently used AutoCad for
simple 2D drawings, so some things are intuitive to me - but Sketchup
has its own way of doing things, and I've seen comments that
familiarity with ACad or similar programs can hinder learning Sketchup
to some extent.

I wouldn't doubt that! AutoCAD does many things in a counterintuitive
manner. Not that it is *less* efficient but, rather, to a new user,
AutoCAD looks "bent". To a seasoned user, something *else* would
look "bent"!

 

[Don Y]

Hi Peter,

I think you're being somewhat too pessimistic (or something) about
this. I'd expect virtually everyone to have _some_ media player on
their machine, so the only requirement is that the user may have to
tell Acrobat (or Foxit or...) what that player is, and where to find
it.

But the player may not support the particular CODEC used in the
video! I was hoping that Acrobat would "standardize" the format
of these animations/presentations so that *it* could present THE
necessary CODEC. That way, all *I* would have to do is verify
there was a version of Reader available for the likely OS's
that users would encounter. If there is something *else* that
imposes requirements on the playback, then I have to ensure
a media player/CODEC exists for each of those OS's, as well
(and pray that "Joe's Freeware FOOBAR CODEC" is at least
as good as the "Mainstream" CODEC/player that I would expect to
be used)

<frown> As I said, I'll have to explore this in more detail.
It may be that PDF's are the wrong "container"...

 

[Don Y]

Hi Robert,

While it won't net you the best possible compression, some
approximation of "everyone" supports MPEG-1.

As probably GIFs, etc. I have to look into how Acrobat massages
files imported into the PDF -- does it preserve original encodings
or transcode to something else "equivalent", etc.

Likewise, I need to see how scripting is implemented (requiring
external helpers -- like JVM?) and whether it might be "more
self-contained" to just arrange to do animations programmatically
instead of as "canned video".

(or, single-stepped GIFs)

Sheesh! I've had tools that could do this for more than a decade
(unportably). Disturbing to see that this functionality hasn't
made it into the mainstream in an equivalent form...

 

[Boo]

Are you claiming that the host OS/filesystem will experience *no*

changes outside of those *within* the guest OS's virtual disk
contents when I insert a PCMCIA card, USB device, FW device, PCI
cards, etc.?

And, that the guest OS will be able to *effectively* use each of
these bits of hardware?

If you already have multiple platforms of PCI, PCMCIA etc based hardware then
virtual PCs may not be ideal. USB does seem to work well though IME, using
VirtualBox.

Perhaps the *first* use for these little boxes is to install
VirtualBox, VMware, etc. *there* and prove/disprove this claim...

VirtualBox works well IME, so you could start there. It's pretty well mannered
on Windows anyway, and seems to have not particular issues when I've installed it.

Boo