[Elecraft] "Exciting" manual to match "exciting" K3

[David Woolley (E.L)]

Tom Childers, N5GE wrote:
> On Sat, 8 Mar 2008 20:43:39 -0700, K3KO wrote:

> My experience is that using Acrobat for documentation is a waste of time,
> especially if the text will ever need to be edited.

PDF is described as a "final form" document language.  That means that 
it tries to accurately represent the printed page, but is not editable 
(beyond replacing or adding whole pages).  Conventional printed 
documents are also final form; PDF is a replacement for printed documents.

Final form tends to be very important to marketing people, as they set a 
lot of importance on appearance, rather than contents.  This doesn't 
just include obvious advertisements; all user guides and data sheets 
are, in part, marketing documents.  (Data sheets more than ussr guides, 
as the are more likely to be seen pre-sale.)

It also gives them, and their font vendors, some level of intellectual 
property control, in that they can put technical restrictions on how the 
document is used and they can include font definitions without the user 
being able to hijack them.  Fonts are part of the desire for appearance, 
and, in the modern world, marketing is all about the control of 
intellectual property.

> 
> I worked for a national car loan company that had to keep up with the car loan
> laws in all states in the USA and provinces in Canada.  If one changed it was a
> major emergency as far as changing Repo letters, etc. and took much longer than
> it would have if the company would have just used MS Word, Word Perfect or some

Form letters really need revisable form documents, because you are 
inserting variable length information!  Repossession letters are 
probably not trying to sell to the recipient, although they may use 
visual psychology in other ways.

> On the other hand I worked for a company that provided banking software whose
> documentation in MS Word.  The changing of a document by a documentation
> specialist was accomplished with minimal effort.

That is OK if they are selling to business users of Windows, who are 
likely to have MS Word, and if they don't care about the exact 
pagination of the document, which will change for each different printer 
used.  (I suspect they did care about pagination, but either distributed 
final form documents (on paper) or failed to realise that the pagination 
would vary.)

Apart from lack of of IPR control and layout control, the big problem 
with Word for a more general market is that you need Microsoft software 
to render it correctly, and you need to buy MS Office to do it really 
well.  Part of the aim of PDF is to produce consistent behaviour on as 
many platforms as possible.  Adobe publish a well documented 
specification of the format and allow other people to implement it. 
Microsoft only publish a poorly documented specification, and on the 
strict understanding that it not be used to create products that compete 
with Microsoft; that means that Linux users have to rely on keeping a 
Windows partition, or tools that are based on black box reverse 
engineering, to view Word documents.

If one wants a revisable form document that is universal, the best 
choice would have been HTML, if Microsoft had played fair, but 
Microsoft, for example, never implemented SVG, so line diagrams are 
limited to bitmaps, and they are slow in implementing other areas, only 
doing so when they start losing market share.  They would prefer 
professional documenters to use Word and distribute machine readable 
version in Word, so that everyone has to possess Microsoft software.

If you send me a Word document, I will have to be very interested in 
reading it before I will reboot to Windows to look at it.

>> With the full Acrobat product, you can make an attempt to convert 
>> the PDF to MS Word format. Depending on how structurally complex 
>> the document it, and what the original source authoring software 
>> was, this will be more or less successful -- usually less. If the
>> conversion does replicate the original

I suspect, what you mean by structurally complete is that it uses tagged 
PDF.  Tagged PDF basically means adding the equivalent HTML markup as an 
overlay to a PDF document and was primarily introduced because of 
accessibility legislation.  Assistive technology needs to understand the 
intent of the formatting if it is going to successfully render documents 
in significantly different formats, e.g. speech.

There are options in the Acrobat tools to create tagged PDF 
automatically from properly written Word documents, however most Word 
documents are not properly written from an accessibility point of view, 
and if one is serious about accessibility, one should not rely just on 
automatic tagging.  (The automated support is probably only for Word 
because of the near monopoly that Word has in business use.)

Making documents accessible does have the side effect of making them 
more revisable.

Incidentally, although I don't know if this is already done, the 
operating guide sections of the K2 and K3 manuals almost certainly ought 
to be distributed in tagged PDF format as I suspect there are a 
significant number of operators who are blind or partially sighted, and 
would therefore benefit from "screen readers" or reflowed, enlarged text.


-- 
David Woolley
"The Elecraft list is a forum for the discussion of topics related to 
Elecraft products and more general topics related ham radio"
List Guidelines <http://www.elecraft.com/elecraft_list_guidelines.htm>