oXygen vs. Oxygen

[mbakeranalecta]

The product name is spelled "Oxygen" and "oXygen" in the manual, in nearly equal proportions. "Oxygen" occurs 212 times and "oXygen" 188 times. "Oxygen" will actually occur far more often in the output, however, as that is how the product variables are defined.

The same inconsistency occurs in the interface. The interface also occasionally uses "".

We should be consistent in this. (Though we should be careful when me make it consistent not to change any case-sensitive file or variable names mentioned in the text.)

What is the preference? Oxygen or oXygen?

[georgebina]

The actual name is <oXygen/> but this may create issues if it is not processed correctly, thus we removed the angle brackets and resulted oXygen, keeping the spelling. Because sometimes "oXygen" started a phase it looked strange to start with a lower case letter so that moved to Oxygen, keeping an upper case X does not make sense.

There is no strong preference for any of these forms for the user guide. I will prefer the oXygen form because the spelling matches the logo.

In any case, we should use the key "product" to refer to the product name and then we can easily change it everywhere. I guess the current "Oxygen" references are directly as text while most "oXygen" references come from referring the "product" key. The solution should be to replace Oxygen and oXygen with a reference to the product key.

[raducoravu]

It depends from case to case, in some topics for example we have constructs like "Oxygen_INSTALL_DIR" which make no sense to be replaced with the product name. My personal opinion is that we have too much usage of the oxygen word in the user's manual. In some of the user manual topics I created recently I've started to use "the application" instead of Oxygen. It is the Oxygen User Manual, in my opinion it does not need to have phrases like "If you check this setting Oxygen will ....".

[mbakeranalecta]

Re "Oxygen_INSTALL_DIR", I agree. A variable should represent the same piece of information, not the same string.

I don't agree about us "the application" rather than the product name, however. Four reasons:

1. Specific is always better than general. The reader has to decode "the application" and mentally replace it with the product name. That is one more piece of cognitive overhead when the user's brain is already trying to solve a problem.
2. It reduces the information scent and compromises the reader's ability to recognize that the content they have found it the content they are looking for. Readers are increasingly seeking information on the Web and when you Google for something, you don't know that you have landed in the Oxygen User Manual. Every page is page one, and every page has to establish its context. Making sure that the product name is mentioned explicitly helps to do that.
3. We are currently publishing 7 separate manual on the Web. The have broadly similar content, but many differences. A user who arrives via a web search will not necessarily recognize which of the manuals they have landed on. Mentioning the product name is important to help them recognize where they are. (An important related problem is that there is currently no easy way for them to get from a page on Editor Plug in to the same page on Author standalone, for instance.)
4. Google does not like duplicate content. Using explicit product names will help it to recognize that the same topic appearing in different manual is actually a different page. It will also help Google to recognize that this is a page about Oxygen, which is important if you want the manual pages to rank well when people search for help on Oxygen.

[raducoravu]

Actually every page of our user's manual has the product name written in the top left part of the screen:

http://www.oxygenxml.com/doc/ug-oxygen/#topics/installation.html

[georgebina]

So what do you think about replacing, where it makes sense, the occurrence to oXygen or Oxygen with a keyref to the product key? I think this should solve the consistency issue and then we can very easily decide the desired form.

[mbakeranalecta]

Radu, that is true, but eye-tracking studies consistently show that people do not look at the navigation frame of a website. Their attention goes straight to the first paragraph of text, where they make their decision to stop or move on in a matter of seconds. The vital information that tells them they are in the right place needs to be in that paragraph. The product name should be there at least.

And for Google, keyword density still matters, so using the name is good for SEO.

George: Yes, I definitely think we should replace it where it makes sense. I can do that today or tomorrow, but I think we should do a merge from master to dev immediately before and a merge from dev to master immediately afterward.

I also think that we should come up with a way to mark the instances that should not be replaced with product, so that it will be easier to audit the use of product in the future. I'm not sure if DITA has a suitable element for this. If not, I would suggest creating a specialization of called that would be used to mark any instance of a word that is normally replaced by a key reference. This would be post-6.1, of course.

[georgebina]

The master and dev are the same now.

[mbakeranalecta]

I have made the changes and committed them. There were a number of cases where it was not clear what the right thing to do was. They are listed below. I have not made a change in any of these cases.

Product variable issues

Indexterm

The word Oxygen occurs frequently in indexterm entries. However, you can't insert product variable in an indexterm.

I'm not sure name should be in index term anyway. Indexes are not like web search. You already know the context when you use the index, so you really don't need the product name in there.

Terms that may be proper names of components

It is not clear if the word Oxygen in the following cases is part of the proper name of each component, or if it is the name of the product. That is, is there a component named "Oxygen API" which is independent of the particular package you are using, or should this be API?

    Oxygen URLStreamHandler

    Oxygen HTTP URLStreamHandler

    Oxygen Scripting license key

    Oxygen API 

    oXygen License Servlet

    Oxygen CSS extensions

    oXygen classes

Weh help plugin name

I assume that in this case the Oxygen WebHelp plugin is the name of a component, and should not use the product variable. However, I don't know if there is a separate plugin for DITA or if they are the same thing. And if they are the same thing, what is the correct name? (And is Plugin part of the name, meaning it should be capitalized, on not, meaning it should be lowercase?)

    the Oxygen WebHelp plugin
    Oxygen WebHelp Plugin for DITA

Referring to the website

I found both capitalizations of oXygen used to refer the the website. However, I recommend that all references be replaced by the URL. This just makes it easier for the user to get there.

    Oxygen website
    oXygen website

Passages in which the meaning is not clear

In the following, is the reference to the Oxygen XML Author product alone?

  <title>Save a new document with a predefined file name pattern</title>
  <body>
    <section>
      <title>Question</title>
      <p>Is it possible using the SDK to get Oxygen Author to automatically generate a filename
        comprising a UUID plus file extension?</p>

      <p>You can use this mechanism to overwrite any kind of resource located in the main Oxygen JAR
        library. The folder structure in the endorsed directory and in the main Oxygen JAR must be
        identical. </p>

In the following, the reference to "Oxygen standalone version" is a problem. Presumably any version will do. In fact such frameworks shoud work in an Eclipse version as well, thought we usually use standalone to mean "not eclipse" as opposed to "not web". Perhaps the right word here is "desktop version".

But that still leaves us with the question of whether "Oxygen" here should be replaces with the product key, since this string will actually occur in the manual for one particular version. The root of the problem here is that the Oxygen component is really a different version from Author/Editor/Enterprise and should really have its own version of the manual.

    <topic id="author_component_customization">
      <title>Customization</title>
      <body>
        <p>For a special type of XML, you can create a custom framework (which also works in an Oxygen standalone version). <ph
            keyref="product"
            /> already has frameworks for editing DocBook, DITA, TEI, and so on. Their sources are available in <xref
            href="http://www.oxygenxml.com/developer.html#XML_Editor_Authoring_SDK" scope="external"
            format="html"
          >the Author SDK</xref>. This custom framework is then packed in a zip archive and used to deploy the component.</p>
        <p>The following diagram shows the components of a custom framework.</p>
        <image href="../img/diag_CustomFramework.png"/>

Same issue with "Oxygen standalone".

     <topic id="component_customization_example">
      <title>Example - Customizing the DITA Framework</title>
      <body>
        <p>If you look inside the <filepath>bundle-frameworks\oxygen-frameworks</filepath> folder
          distributed with the <xref href="http://www.oxygenxml.com/oxygen_sdk.html#oXygen_standalone_applet_integration"
            format="html" scope="external">Author Component sample project</xref>, it contains a
          document type framework folder. Customizations which affect the framework/document type
          configuration for the component should first be done in an Oxygen standalone installation.</p>

This is a case of the name being written "". I hesitated to change this one as it is the name of a licence agreement and should agree with the document.

      <p>The licensing terms and conditions for the Author Component are defined in the <xref
    href="http://www.oxygenxml.com/sdk_agreement.html" format="html" scope="external"
      ><b>&lt;oXygen/&gt; XML Editor SDK License Agreement</b></xref>.

This is a case of the name occurring in code comments. Not sure if this needs to use the product variable.

          <codeblock outputclass="language-java">  /**
       * Sample implementation for the "Check Out" method.
       *
       * @param pluginWorkspaceAccess The plugin workspace access (Workspace Access plugin).
       * @throws MalformedURLException 
       */
      private void checkOut(StandalonePluginWorkspace pluginWorkspaceAccess) throws MalformedURLException {
        //TODO Show the user a custom dialog for browsing the CMS
        //TODO after the user selected the resource create an URL with a custom protocol 
        // which will uniquely map to the resource on the CMS using the URLHandler
        //something like:
        URL customURL = new URL("mycms://host/path/to/file.xml");
        //Ask Oxygen to open the URL
        pluginWorkspaceAccess.open(customURL);
        //Oxygen will then your custom protocol handler to provide the contents for the resource "mycms://host/path/to/file.xml"
        //Your custom protocol handler will check out the file in a temporary directory for example and provide the content from it.
        //Oxygen will also pass through your URLHandler if you have any relative references which need to be opened/obtained.
      } </codeblock>

One of the rare cases in which the docs for one version refer to another version.

    <topic id="debug-plugin">
      <title>Debugging a Plugin Using the Eclipse Workbench</title>
      <body>
        <p>To debug problems in the code of the plugin without having to re-bundle the Java classes of
          the plugin in a JAR library, follow these steps:<ol id="ol_ops_m3p_hj">
            <li>Download and unpack an <xref
                href="http://www.oxygenxml.com//InstData/Editor/All/oxygen.tar.gz" format="gz"
                scope="external">all platforms standalone version</xref> of Oxygen XML Author/Editor to
              a folder on your hard drive.<note>Name the folder   
              ...
     <li>Start the standalone version of Oxygen from the <filepath>OXYGEN_DIR</filepath> and in
              the <b>Document Type Association</b> Preferences page edit the document type (for example
                <b>DITA</b>). In the <b>Classpath</b> tab, add a reference to your Project's
                <filepath>classes</filepath> directory and in the <b>Extensions</b> tab, select your
              custom <apiname>StylesFilter</apiname> extension as a value for the <b>CSS styles
                filter</b> property. Close the application to save the changes to the framework
              file.</li>      

Here is a case where the word "desktop" is used -- and is capitalized. Probably shouldn't be capitalized.

    <p>A framework developed for the Desktop Oxygen application can then be bundled with an
        Author component in a custom applet. For example the Author demo applet from our web
        site is DITA-aware using the same framework as the Oxygen standalone distribution.</p>
      <p>A custom version of the applet that includes one or more customized frameworks and user
        options can be built and deployed for non-technical authors by a technical savvy user
        using a built-in tool of Oxygen. All the authors that load the deployed applet from the
        same server location will share the same frameworks and options.</p>

An instance of that I did not change because it really is in the interface. This is not consistent with how it appears in Preferences in Eclipse. It should be made consistent, but in the interface first.

        <ph product="editorEclipse authorEclipse developerEclipse">To edit the
    content of your XML documents, use the <uicontrol>&lt;oXygen/> XML</uicontrol> perspective ((<menucascade>
      <uicontrol>Window</uicontrol>
      <uicontrol>Open Perspective</uicontrol>
      <uicontrol>&lt;oXygen/> XML</uicontrol>
    </menucascade>)).</ph></p>

[georgebina]

Re indexterms We can remove the product name from indexterm entries or we can use keyword/@keyref

Re proper names of components:

Oxygen URLStreamHandler
    - fixed to use the product key
Oxygen HTTP URLStreamHandler
    - fixed to use the product key
Oxygen Scripting license key
    - fixed by removing "Oxygen Scripting"
Oxygen API 
    - I cannot find this in the current source
oXygen License Servlet
    - this should be probably extracted as a key, similar to the webhelp plugin one - it refers to the license server used for managing floating licenses for any oXygen installation
Oxygen CSS extensions
    - found one entry, use keyword/@keyref to product 
oXygen classes
    - I cannot find this in the current source

[raducoravu]

I would vote for removing it.

[mbakeranalecta]

Don't now why I keep forgetting about keyword, but I'm for removing Oxygen from the index terms too. I don't think people will be entering it as a term when they are searching the index. I'm wondering, though, if we have logs for the search and index lookups that people have done in the online version of the docs. That would be a good way to verify if people are searching on the name, and it would give us a lot of other useful information about what people are looking for and how.

[georgebina]

Re WebHelp references: the WebHelp product is a set of resources that contain transformations from DITA and DocBook to WebHelp. In case of DITA the transformation is packaged as a DITA-OT plugin while in case of DocBook it is a customization of the DocBook stytlesheets that provide the WebHelp transformation. I updated the documentation in ad91ae0.