[Date Prev][Date Next] [Thread Prev][Thread Next]
[Date Index] [Thread Index] [New search]

Sloppy MIF manual in FM6 (long)



*** This message is posted to the mailing list framers@omsys.com,
*** the News group comp.text.frame, and Adobe's User to User Forum
*** for FM (http://www.adobeforums.com/cgi-bin/webx.fcgi?.ee6b312).
*** Feel free to forward this message to the FrameUsers mailing list,
*** but email me privately before you do so to avoid multiple postings.

Sloppy MIF Reference Manual in FM 6
===================================
Background: The FrameMaker distribution includes a number of 
"Online Manuals" that are not delivered in print. In FM 5.x, these
were available directly from the main online help screen, but in
FM 6 they are only delivered as separate re-designed PDF files.
They are intended for print-out, not for online reading.

I have just reviewed the MIF Online Reference Manual for FM 6. 
I want to point out and warn FM users for the deficiences in this
version. It's obvious that this manual was re-designed, edited and
converted to PDF in a very hasty manner, without having been proof-
read or subjected to the Quality Assurance that should be expected.
[NOTE: I don't have FM 6 myself, but I have access to the release docs.
 I've been assured that it's not the Beta release docs, or similar.]
 
It's very easy to spot the existing errors and typographical glitches,
which never should have been allowed to enter the production phase.
In my opinion, it's a disgrace for Adobe to offer the manual in
this state, and a disservice to all FM users interested in MIF.

Following is a list of errors and deficiences in the manual.
This is quite long, but proves my statements above.
===================================================
In the first chapter, nearly all words in Courier font, including
all MIF keywords, are simply missing from the text!! Examples:
* page 10: "A MIF file must be identified by a or statement at the
            beginning of the file;"
  Should be "A MIF file must be identified by a MIFFile or Book
             statement at the beginning of the file;"
* page 11: "A value of either or . Case is significant."
  Should be "A value of either Yes or No. Case is significant."
* page 11: "Used only by the and statements within the statement
            and the statement within the statement."
  Should be "Used only by the DWindowRect and DViewRect statements 
             within the Document statement and the BWindowRect
             statement within the Book statement."
* page 13: "You can also use the statement to include certain
            predefined special characters in a statement"
  Should be "You can also use the Char statement to include certain
             predefined special characters in a ParaLine statement"

Chapters/appendices are no longer numbered (as they were in 5.5),
but references all throughout the manual haven't been changed to
reflect this. Examples:
* page 60: "For a description of the differences between MIF 6.0 and
            previous versions, see , 'MIF Compatibility.'"
  In 5.5, the cross-ref read "see Appendix C, 'MIF Compatibility.'"
  NOTE the comma that still is there. Apparently, the cross-ref
  formats have not been updated... The link works online, but how are
  you supposed to find the reference in print? (the intended format)
  But on page 68, it's stated: "For more information, see Appendix C,
  'MIF Compatibility.'". The problem is that the appendices are no
  longer numbered... Guess what? This reference is plain text, not a
  cross-reference or link at all! 
* page 65: "see the MIF statement descriptions in Chapters 3 through 5."
  Unfortunately, the chapters are no longer numbered...

The font style used for cross-references (links) vary throughout the
manual. Many references are in the plain style, while others are
underlined, or in italics, or both. These are the same type of
references, and they can vary in font style on the same page! Also,
some cross-refs use a larger font size than the surrounding text.

Misformatted paragraphs. Examples:
* page 7: "For a description of the differences between the MIF
           statements for this version of your FrameMaker product and
           earlier versions, see , 'MIF Compatibility.'Style conventions"
  The last text "Style conventions" is in fact a level-2 heading that
  of course should be a separate paragraph.
* page 10: "tokendatawhere token represents one of the MIF statement..."
  This entire paragraph is set in Courier font, even though only the
  first part "<token data>" should be a separate paragraph in Courier.

Some text in graphic frames have been incorrectly displaced to overlay
other parts, or to partly disappear (pages 287-289).

All tables have been reformatted, without exceptions. On page 38,
the following example is given:
"For example, you could change the format of the previous table to
include shaded rows and a different ruling style:"
followed by a table with no shaded rows and the same ruling style...
The point in showing how a 10% gray fill is implemented becomes
somewhat hard to get. (This was perfetcly OK in the 5.5 version.)

There are bad line and page breaks in the manual, that apparently are
hard-coded breaks left over from the 5.5 version that haven't been 
corrected in the new version. (page 61, 97, 142, 157)

Numbered lists are sometimes not restarted from 1 (page 247).

There are references to outdated things, like filenames on NeXT
computers (!), and the since long gone FrameReader product.

Some references to FM versions have not been updated, for instance:
page 257: "This appendix lists the MIF statements that are new or have
changed in version 5.5". This should obviously be "version 6.0".


/Thomas "Eagle-eye" Michanek
(who cannot stop to wonder if this is yet another example of how
FrameMaker is treated internally at Adobe)
- - - - - - - - - - - - - - - - - - - - - - - - -
Thomas Michanek, [Michagon], Linkoping, Sweden
       FrameMaker/UNIX/MIF/scripting expert
EMAIL: mailto:Thomas.Michanek@telia.com
WWW:   http://go.to/framers , or go directly to:
       http://w1.133.telia.com/~u13304072/framers
       *  U P D A T E D   O N   J U N E   2 6  *
- - - - - - - - - - - - - - - - - - - - - - - - -
Subscribe to the "Free Framers" list: send an email to
majordomo@omsys.com with "subscribe framers" in the body


** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **