Profiled content in reusable file.

[mbakeranalecta]

The steps to open the preferences dialog are repeated many times in the docs, and they are heavily profiled because of the differences between standalone and the various flavors of Eclipse. Often the profiling is inconsistent from one topic to another, and they are painful to debug.

To address this, I looked for a way to move the initial steps of the menucascade to a reusable file in such a way that the profiling would be in the reusable content, not in each instance where it is used. This means having a single keyref or conkeyref that is used wherever the user has to call up the preferences dialog.

This means having a single keyref (or conkeyref) that pulls in . So far I have not been able to find a way to do it. Here are some of the obstacles I have encountered:

• Because it is only part of a menucascade that I am using, I need to use ids on the first and last uicontrol of each sequence and use conref and conrefend to select just the uicontrols I want. The problem is, I also have to apply the profiling to these same uicontrols, and:
  • I can't use the same id with different profiling because the ids are unique across a file, regardless of profiling.
  • I can't use ids at the start and end of a whole block of profiled uicontrols because then the ids are not visible to the profiles that don't include them, breaking the conref.
  • I can't put a wrapper element like ph around a block of uicontrols because ph is not allowed inside menucascade.

All of which means there is no way that I can find to profile in the reusable content. So I looked for a way to profile at the map level. I came up with the structure shown in commit 26c28b1 in C:\Users\Mark\userguide\DITA\reusables\reusables.ditamap and C:\Users\Mark\userguide\DITA\reusables\topics\reusable.menu-elements.dita.

This approach uses double indirection, but it validates fine. However, it does not build correctly. The build fails with:

[conref] : Fatal Error! Error reported by XML parser processing file:/C:/Users/Mark/userguide/DITA/temp/webhelp/oxygen_dita_temp/reusables/reusables.ditamap: Premature end of file. Cause: org.xml.sax.SAXParseException; Premature end of file.

The version of reusables.ditamap in temp is actually empty.

I don't know if this is a bug or if the double indirection I am trying to do is illegal, but either way, I'm stumped.

Can anybody think of a way to do this, because it would really help clean up the source, reduce authoring effort, and reduce errors if we could make it work. It probably applies to a number of other menucascades besides preferences.

[georgebina]

I think this should be split into 2 parts
one will be a reference to product preferences linking to the configuring-options key - this will be the part that will help the user get to the preferences dialog
the other part will be a menu cascade that will identify the exact preference page where the user should go - this is in general the same for all products

For example something that is currently profiled as
<p>The <uicontrol>Archive</uicontrol> preferences panel is opened from menu <menucascade>
<uicontrol product="author developer editor">Options</uicontrol>
<uicontrol product="editorEclipse authorEclipse developerEclipse">Window</uicontrol>
<uicontrol>Preferences</uicontrol>
<uicontrol product="editorEclipse developerEclipse">oXygen XML Editor</uicontrol>
<uicontrol product="authorEclipse">Author</uicontrol>
<uicontrol>Archive</uicontrol>
</menucascade>.</p>

can be replaced with

<p>The <uicontrol>Archive</uicontrol> preferences panel is opened from <xref
keyref="configuring-options"/> then select <menucascade>
<uicontrol>Archive</uicontrol>
</menucascade>.</p>

[georgebina]

Alternatively, we can conref a first menucascade that gets the user to the preferences dialog instead of xref-ing to the configuring options topic - the second part will be similar, a second menucascade that defines the path within the oXygen options.

[mbakeranalecta]

That's what I am inclined to do too. I don't think linking saves any space or simplifies the current page in this case, so my inclination is to do:

Open the preferences dialog (Options>Preferences) and go to Editor > Edit Mode > Text.

That reads naturally enough, and it does coincide with the switch from the app menu system to the dialog's tree navigation, so the split is no bad thing.

[mbakeranalecta]

I have tested this solution and it works. I have created a reusables directory with its own ditamap (where we can set keys) and included that map (reusables.datamap) in the main ditamap.

I have created a topic for reusable menucascades: \DITA\reusables\topics\reusable.menu-elements.dita

It defines a profiled menu cascade for entering the preferences dialog. It also defines a reusable phrase for saying "open the preferences dialog".

  <topic id="reusable.menucascade">
    <title>Reusable menucascade elements</title>
    <body>
    <p>Preferences page </p>
      <p><menucascade id="preferences">
          <uicontrol product="editor author developer svnClient">Options</uicontrol>
          <uicontrol product="editorEclipse developerEclipse authorEclipse">Window</uicontrol>
          <uicontrol>Preferences</uicontrol>
          <uicontrol product="editorEclipse">oXygen XML Editor</uicontrol>
          <uicontrol product="authorEclipse">oXygen XML Author</uicontrol>
          <uicontrol product="developerEclipse">oXygen XML Developer</uicontrol>
        </menucascade>
        <ph id="open-the-preferences-page"> open the <uicontrol>Preferences</uicontrol> dialog
        (<menucascade conkeyref="reusable.menus/preferences"><uicontrol/></menucascade>)</ph>
      </p>
    </body>
  </topic>

These are conkeyref-ed into the text like this:

<ph conkeyref="reusable.menus/open-the-preferences-page"/>

This should now be the standard way to tell the user to enter preferences.

[georgebina]

This looks fine!
There is an additional case, if this was not complex enough :). The Preferences on Eclipse on Mac OS X are located in Eclipse->Preferences instead of Window->Preferences... Shall we try to include this information as well? For example we can say

<uicontrol product="...">Window (Eclipse on Mac)</uicontrol>

What do you think?
Or we can just use a generic "Eclipse Preferences" entry that will replace Window->Preferences and Eclipse->Preferences and this may link to a topic that describes the two ways of accessing the preferences dialog on Eclipse?

[mbakeranalecta]

I tried doing this:

    <p>
      <ph id="preferences-page" >
        <ph product="authorEclipse developerEclipse editorEclipse">go the Eclipse preferences and choose</ph>
        <uicontrol product="editorEclipse">oXygen XML Editor</uicontrol>
        <uicontrol product="authorEclipse">oXygen XML Author</uicontrol>
        <uicontrol product="developerEclipse">oXygen XML Developer</uicontrol>
        <menucascade product="editor author developer svnClient">
          <uicontrol>Options</uicontrol>
          <uicontrol>Preferences</uicontrol>
        </menucascade></ph>
    </p>
    <p>
      <ph id="open-the-preferences-page">open the <uicontrol>Preferences</uicontrol> dialog (<ph
          conkeyref="reusable.menus/preferences-page"/>)</ph>
    </p>

But unless you run it all together on one line, it produces extraneous spaces in both the editor and the output. (And if we do put it all on one line, someone will eventually hit the format and indent button without realizing the consequences.)

So maybe the best alternative it to simply make "open the Preferences dialog" a link to a topic that explains the variations. Most readers will not need to follow that link most of the time (the location is pretty easy to find, and once you do it once you will know) so its not going to harm usability any. In fact, it may improve usability for most: one less piece of information on the page is always good as long as its not information you need.

[georgebina]

We can enclose the preferences-page in a pre element instead of p and then make sure we have the exact space that we want there. In general pre will be defined as a preserve space element in the schema, in the CSS and in the oXygen default formatting options so the whitespace will be preserved there. A good definition will be

<pre><ph id="preferences-page"><ph product="authorEclipse developerEclipse editorEclipse">go the Eclipse preferences and choose </ph><uicontrol product="editorEclipse">oXygen XML Editor</uicontrol><uicontrol product="authorEclipse">oXygen XML Author</uicontrol><uicontrol product="developerEclipse">oXygen XML Developer</uicontrol><menucascade product="editor author developer svnClient"><uicontrol>Options</uicontrol><uicontrol>Preferences</uicontrol></menucascade></ph></pre>

(you need to scroll right to get the entire content of the pre element)

The link was also my initial proposal as that can explain how you can get to that dialog and once you know that then you do not need to follow the link anymore.

Best Regards,
George

[mbakeranalecta]

Clever! That certainly works.

I've added it to reusable.menu-elements.dita so that we have it available. I am going to implement the use of open-the-preferences-page across the docs. That way we can change between using the link and using the expanded path just by changing the definition of open-the-preferences-page.

I've also added Open-the-preferences-page (initial cap) for the same phrase used at the beginning of a sentence.