cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Showing results for 
Search instead for 
Did you mean: 

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

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

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.

Tags (2)
12 REPLIES 12

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

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-----

public vs. private

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?

public vs. private

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

public vs. private

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

-Brandon 🙂


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



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.
>
> ----------

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

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.
>>
>

public vs. private

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!"


public vs. private

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.


public vs. private

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.