Epic6: What controls the "completeness check," and how can I override it?

[GarenTorikian]

We're starting to create Schematron files to validate our XML content, now that support for them has been introduced in Arbortext Editor 6.

However, when writers on the team use the "Check Completeness" feature, they receive a list of warnings that are completely safe, in addition to legitimate Schematron issues. For example:

DITA Markup ProblemsWARNING:

"foo.xml" is missing an xml:lang attribute on the root element.

DITA Reference ProblemsWARNING:

Unusual value "new-window:PDF" specified for type attribute on xref element in "foo.xml".

WARNING: External/Peer reference to "bar.pdf" on xref element in "foo.xml" is not represented in a correct format

While Arbortext may think that every root element, for example, needs an xml:lang attribute defined, we put ours in during build time in order to support multiple languages. And new-window:PDF is also an attribute used for special purposes for the build.

Is there some way I can override or "block" checks that I know are not necessary? At the least I'm looking for just running Schematron against the file, but what would be best is Schematron + well-formedness / context rules.

[bibach]

All of the checks of DITA constraints beyond what is enforced by the
DTD are part of the "enhanced completeness check" provided by the
Arbortext DITA application. If you just want the regular completeness
check, you could redefine the command alias invoked by the "Check
Completeness" menu and toolbar button:

alias CheckCompleteness cc -full

-Brandon 🙂


On Wed, Aug 10, 2011 at 6:08 PM, Garen Torikian
<gtorikian@salesforce.com> wrote:
> We're starting to create Schematron files to validate our XML content, now
> that support for them has been introduced in Arbortext Editor 6.
>
> However, when writers on the team use the "Check Completeness" feature, they
> receive a list of warnings that are completely safe, in addition to
> legitimate Schematron issues. For example:
>
> DITA Markup ProblemsWARNING:
>
> "foo.xml" is missing an xml:lang attribute on the root element.
>
> DITA Reference ProblemsWARNING:
>
> Unusual value "new-window:PDF" specified for type attribute on xref element
> in "foo.xml".
>
> WARNING: External/Peer reference to "bar.pdf" on xref element in "foo.xml"
> is not represented in a correct format
>
>
>
> While Arbortext may think that every root element, for example, needs an
> xml:lang attribute defined, we put ours in during build time in order to
> support multiple languages. And new-window:PDF is also an attribute used for
> special purposes for the build.
>
> Is there some way I can override or "block" checks that I know are not
> necessary? At the least I'm looking for just running Schematron against the
> file, but what would be best is Schematron + well-formedness / context
> rules.
>
> -----End Original Message-----

[ebenton]

I know that by default, Arbortext Editor won't let you use the FOSI panels to edit the "public" version of the FOSI (i.e. the one in the doctype folder with the DTD, etc.).
You must make a "private" copy of the FOSI and edit that one using the panels.

Can anyone point me to some documentation somewhere that describes this whole public versus private nature of Editor files? I suspect that Document Architect documentation, which I do not have, may describe this, since you can use Document Architect to edit the public Arbortext Editor files.

Semantically, I know the difference, but does anyone know where this public vs. private concept is described in writing?

[ptc-3050150]

I got my understanding from the discussions about the "custom" folder - when it scans which in what order and which one takes precedence.

hth,
John

[bibach]

The "help 711" topic sort-of-kind-of-briefly touches on this (at least
in the 5.4 Help Center).

-Brandon 🙂

[GarenTorikian]

In Reply to Brandon Ibach:

But how does Arbortext decide what counts as "completeness"? If the type attribute on an xref, for instance, accepts CDATA, it shouldn't matter if I put new-window:PDF or kalamazoo or what-have-you. How come the check flags it as a warning?

All of the checks of DITA constraints beyond what is enforced by the
DTD are part of the "enhanced completeness check" provided by the
Arbortext DITA application.  If you just want the regular completeness
check, you could redefine the command alias invoked by the "Check
Completeness" menu and toolbar button:

alias CheckCompleteness cc -full

-Brandon 🙂


On Wed, Aug 10, 2011 at 6:08 PM, Garen Torikian
@<gtorikian@salesforce.com> wrote:
> We're starting to create Schematron files to validate our XML content, now
> that support for them has been introduced in Arbortext Editor 6.
>
> However, when writers on the team use the "Check Completeness" feature, they
> receive a list of warnings that are completely safe, in addition to
> legitimate Schematron issues. For example:
>
> DITA Markup ProblemsWARNING:
>
> "foo.xml" is missing an xml:lang attribute on the root element.
>
> DITA Reference ProblemsWARNING:
>
> Unusual value "new-window:PDF" specified for type attribute on xref element
> in "foo.xml".
>
> WARNING: External/Peer reference to "bar.pdf" on xref element in "foo.xml"
> is not represented in a correct format
>
>
>
> While Arbortext may think that every root element, for example, needs an
> xml:lang attribute defined, we put ours in during build time in order to
> support multiple languages. And new-window:PDF is also an attribute used for
> special purposes for the build.
>
> Is there some way I can override or "block" checks that I know are not
> necessary? At the least I'm looking for just running Schematron against the
> file, but what would be best is Schematron + well-formedness / context
> rules.
>
> ----------

[ptc-953343]

Check completness is normally checking whatever constraints the DTD/schema
enforce. Did PTC add additional functionality for DITA and enforce some of
the rules that are in the spec but can't be encoded in the DTD/schema?
That would be one possiblity.

..dan

>
>
> In Reply to Brandon Ibach:
> But how does Arbortext decide what counts as "completeness"? If the type
> attribute on an xref, for instance, accepts CDATA, it shouldn't matter if
> I put new-window:PDF or kalamazoo or what-have-you. How come the check
> flags it as a warning?All of the checks of DITA constraints beyond what is
> enforced by the
> DTD are part of the "enhanced completeness check" provided by the
> Arbortext DITA application. If you just want the regular completeness
> check, you could redefine the command alias invoked by the "Check
> Completeness" menu and toolbar button:
>
> alias CheckCompleteness cc -full
>
> -Brandon 🙂
>
>
> On Wed, Aug 10, 2011 at 6:08 PM, Garen Torikian
> <gtorikian@salesforce.com> wrote:
>> We're starting to create Schematron files to validate our XML content,
>> now
>> that support for them has been introduced in Arbortext Editor 6.
>>
>> However, when writers on the team use the "Check Completeness" feature,
>> they
>> receive a list of warnings that are completely safe, in addition to
>> legitimate Schematron issues. For example:
>>
>> DITA Markup ProblemsWARNING:
>>
>> "foo.xml" is missing an xml:lang attribute on the root element.
>>
>> DITA Reference ProblemsWARNING:
>>
>> Unusual value "new-window:PDF" specified for type attribute on xref
>> element
>> in "foo.xml".
>>
>> WARNING: External/Peer reference to "bar.pdf" on xref element in
>> "foo.xml"
>> is not represented in a correct format
>>
>>
>>
>> While Arbortext may think that every root element, for example, needs an
>> xml:lang attribute defined, we put ours in during build time in order to
>> support multiple languages. And new-window:PDF is also an attribute used
>> for
>> special purposes for the build.
>>
>> Is there some way I can override or "block" checks that I know are not
>> necessary? At the least I'm looking for just running Schematron against
>> the
>> file, but what would be best is Schematron + well-formedness / context
>> rules.
>>
>

[ptc-1908075]

Hi Ed! Thanks for asking this! I realized I need to add it to my book.

I agree that any documentation on this would probably come with Document
Architect, which you and I don't have.

Here is my understanding of the situation:

A public FOSI is the "doctype" FOSI, which is the default FOSI. A
public/doctype FOSI has the same name as the doctype and is in the same
directory with the DTD. For example: DocBook.dtdand DocBook.fos would be in the
DocBook directory, along with DocBook.dcf and other doctype files.

A private FOSI is considered a "document" FOSI. A private/document FOSI does not
have the same name as the doctype. However, a private FOSI may have the same
name as an.sgm or .xml file. If a FOSI is in the same directory as a document
with the same name, that FOSI is used when the document is opened instead of the
public/doctype FOSI. For example,user-manual.fos is used
when user-manual.xml (in the same directory) is opened in Arbortext Editor,
assuming they both use the same DTD. Note that if a FOSI and a document with the
same name are not in the same directory, the public/doctype FOSI is used when
the document is opened.

Clear as mud? Please let me know any questions you may have.

Suzanne Napoleon
www.FOSIexpert.com
"WYSIWYG is last-century technology!"

[JasonBuss]

Truth be told, I got so flustered with the FOSI panels after upgrading
to 5.3, I pretty much abandoned them for the tagged view or a text
editor.



I have found an issue where if I try to copy and paste an existing
pageset to create a new pageset, or to create a pageref, using the
panels, I would lose one or more pagesets (meaning just the pageset
wrapper tags with empty headers/footers). I do not dare touch the
pagespecs with the FOSI panels anymore.



And I never had the problem with Adept 7 thru 9, or Epic 5.0-5.1F. Just
after we upgraded to 5.3.

[ebenton]

We have not gone beyond Arbortext 5.2 yet. I have been using the FOSI panels for as long as I have been editing FOSIs. The down-side of this is that I am not intimately familiar with the OUTSPEC DTD. When I use a text editor I am never sure of where certain FOSI elements within an e-i-c can be located relative to other elements in the e-i-c and within <att> tags, etc. and what the attribute names and values are. All of this stuff is resolved for you by the panels.
Another advantage of the panels is that you can make a FOSI change without saving the FOSI, apply the change and see the results (Print Preview is great for this.) - all without shutting down Arbortext Editor and re-launching it to apply the changes.
Our next step is Arbortext 6.0. Maybe the panels will be problematic enough at that time so that I stop using them.

[ptc-1908075]

Jason,

I remember that problem with the pageset style panel mangling the markup. I
don't recall it happening recently in 5.3, but maybe like you I learned to avoid
the problem by using the tagged editor. I'll have to check ...

<plug>My FOSI tutorials explore the strengths of the two FOSI interfaces because
they are best used together. For example, show ids in the tagged editor, Resolve
in the style panels.</plug>

Suzanne


----------

[bibach]

The additional checks, such as those involving the format of xrefs,
are based on requirements in the DITA specification, as Dan suggested.
These are what constitute the "enhanced completeness check" provided
by the Arbortext DITA application. You can read about this by typing
"help 14960" at the Editor command line.

Running the "alias" command I mentioned will bypass the enhanced
completeness check and just run the normal one, which only checks the
document for validity against the DTD or schema.

-Brandon 🙂


On Thu, Aug 11, 2011 at 1:39 PM, Garen Torikian
<gtorikian@salesforce.com> wrote:
>
>
> In Reply to Brandon Ibach:
>
> But how does Arbortext decide what counts as "completeness"? If the type
> attribute on an xref, for instance, accepts CDATA, it shouldn't matter if I
> put new-window:PDF or kalamazoo or what-have-you. How come the check flags
> it as a warning?
>
> All of the checks of DITA constraints beyond what is enforced by the
> DTD are part of the "enhanced completeness check" provided by the
> Arbortext DITA application. If you just want the regular completeness
> check, you could redefine the command alias invoked by the "Check
> Completeness" menu and toolbar button:
>
> alias CheckCompleteness cc -full
>
> -Brandon 🙂
>
>
> On Wed, Aug 10, 2011 at 6:08 PM, Garen Torikian
> <gtorikian@salesforce.com> wrote:
>> We're starting to create Schematron files to validate our XML content, now
>> that support for them has been introduced in Arbortext Editor 6.
>>
>> However, when writers on the team use the "Check Completeness" feature,
>> they
>> receive a list of warnings that are completely safe, in addition to
>> legitimate Schematron issues. For example:
>>
>> DITA Markup ProblemsWARNING:
>>
>> "foo.xml" is missing an xml:lang attribute on the root element.
>>
>> DITA Reference ProblemsWARNING:
>>
>> Unusual value "new-window:PDF" specified for type attribute on xref
>> element
>> in "foo.xml".
>>
>> WARNING: External/Peer reference to "bar.pdf" on xref element in "foo.xml"
>> is not represented in a correct format
>>
>>
>>
>> While Arbortext may think that every root element, for example, needs an
>> xml:lang attribute defined, we put ours in during build time in order to
>> support multiple languages. And new-window:PDF is also an attribute used
>> for
>> special purposes for the build.
>>
>> Is there some way I can override or "block" checks that I know are not
>> necessary? At the least I'm looking for just running Schematron against
>> the
>> file, but what would be best is Schematron + well-formedness / context
>> rules.
>>
>

[steve.thompson4]

I guess I'm spoiled by being where I am, but we DO have Architect, and I wouldn't want to do FOSI without it. Hate the panels myself, for the most part. Only use them to be certain which <e-i-c> is being applied to a given element in a specific context.

Otherwise, all my changes/analysis/whatever is done in the FOSI Editor. Keeps the structure clean and allows doing a number of things that I've not seen or heard were possible in the panels. A text editor on its own (yes, I've used one rarely) would drive me nuts with double-checking that I hadn't broken anything. And with the FOSI Editor, you can do the same "Apply" without saving until you're satisfied on at least an interim basis.

Long-winded way of saying: really glad we have Architect, and I believe it would be worth the price for you, if it's at all possible.

$.02,
Steve Thompson
+1(316)977-0515
-----End Original Message-----