What is a "PI marker" or "programming instruction marker"

[Jeremy H. Griffith]

On Fri, 30 Nov 2012 06:51:20 -0500, Jim Owens 
<jowens at magma.ca> wrote:

>With due respect for Jeremy, whom I esteem greatly, 

Mutual; Jim is one of our DITA users who writes a
lot of reports of problems he finds.  Real ones.
We love users like that.  ;-)

>I think he may have overstated the case. You can 
>get CHM output from oXygen with a few mouse clicks, 
>and you can easily customize its appearance using CSS. 

That's the theory.  The practice... not.  For the
real picture, have a look at the dita-users group:
  http://groups.yahoo.com/group/dita-users/

Today there are three answers to a post yesterday
asking about adding chapter numbers in xref results.
Not too arcane, right?  The answers are all different,
and one mentioned that:
>>I realized that I had implemented a solution to 
>>display the chapter number in cross-references to 
>>tables and figures, but not for an <xref> that 
>>points to another topic or a reltable link!   

That's because the fix has to be made in several 
places in the XSLT, which is largely undocumented.
What happens is you try out the "recipes" you get,
often without understanding why they work (or not).
Then go back to the list with new questions.  This
is not a fast process...

And while CSS, especially CSS 3.0, can do a lot, 
it cannot add missing content, a frequent issue.
Like in the one above.

>There are also some ready-made parameter controls in 
>oXygen, for example to create breadcrumbs (although 
>I just tried that option and I don't see them in 
>the output).

Yes, that's the second problem.  Many features that
work in small demos do not work in real projects.
You always think it is just a simple tweak.  Two
days later, you decide you are almost there...  ;-)

>If you want to go further than that, you can either 
>develop your XSLT skills -- which is a wise strategy, 
>but one you should view as long-term --

Indeed, but only if you have serious programming
talents.  Heavy JS user?  Major FrameScript guru?
You will probably like it.  You absolutely *must*
have the current edition of Michael Kay's book,
"XSLT", from Wrox, only 970 pages (in the 2nd 
Edition, the one by my desk). 

In addition, if you count on the OT for PDF,
you have another, different, language to learn,
XSL-FO (similar name, different syntax).  The
only expert on that is Dave Pawson, whose book
"XSL-FO", O'Reilly, is much shorter, 278 pages.
He also gives classes.  Also, if you find the
free Apache FO processor, fop, inadequate, as
almost everyone does, you need to buy one of
the two commercial FO rendering engines, 
RenderX (a little more than Mif2Go) or Antenna 
House ( a *lot* more, but better Asian support).
There goes the "free" solution...

DITA2Go does not make PDF, but it does make 
Word RTF, with which you can use Word's PDFMaker
(included in Word), Acrobat, or any of the many
free PDF tools (more limited).  Frame makes
much better PDFs, which is the plus for using
it as your XML editor... long as you use the
Frame native PDF, and not the pathetic excuse
in the OT.  ;-)

>or you can develop your Mif2Go/DITA2Go skills, 
>which is a much easier challenge and one that 
>gives you almost as much control of the output. 
>(And if you're missing a control, Jeremy often 
>adds one for you in an amazingly short time.)

Jim should know!  Thanks for the kind words!  ;-)

-- Jeremy H. Griffith, at Omni Systems Inc.
  <jeremy at omsys.com>    http://mif2go.com/