DTD setup and other MIL STD config files

[GigiShep]

I have Arbortext Editor 5.3 configured with AF DTD 38784STD-BV6. Now there is a need for 38784STD-BV9.dtd (DTD v9). What other files do I need and how would I configure AE to create a structure that is compliant with the newer DTD?

I downloaded the "v9" DTD and FOSI and something called a TDT.

When I opened an sgml document that was compliant with my v6 DTD, and associated the v9 DTD with it, it blew up.

That's the good news. At least the content is there. I think I might have to run through context checking and it would create the proper structure. I hope.

But I have no stylesheet. Where does one obtain that?

Basically 2 questions:

What does one need to set up their AE config for an updated DTD of a MIL STD?

How do you get started creating a document with a new DTD? Or, better yet, how do you get an existing one to slide nicely into the updated DTD structure?

[GigiShep]

More info: In the past our custom config was provided. So in this case I am wondering if there is a way to configure AE using the new DTD and new FOSI that we received. I am in unfamiliar territory.

[GarethOakes]

Arbortext ships with a number of "doctypes" and is capable of having other doctypes added to it. Doctypes are added via a "custom folder" process, with the custom folder location supplied via environment variable APTCUSTOM.

The main piece of a doctype is the DTD file, and a related DCF. The DCF is a configuration file which maps DTD elements and attributes to Editor behaviour (eg. what is the bold element called, what should a list insert look like).

The final piece of the puzzle is then the stylesheets. These are conceptually an extension of the DCF but add a lot of detail about what the elements and attributes should look like on screen, in print, on the web, etc.

Does that help? I have no idea what a TDT is, by the way.

[GigiShep]

Thanks Gareth. How are the contents of the custom folder created? In military settings, it seems the military issues the DTD and FOSI... and then what needs to happen? Somehow a stylesheet and apparently a DCF need to be generated. In what ways can you use the DTD and FOSI to create the other necessary files? What tools or expertise are needed? Does PTC have stylesheets tied to military standards?

[GarethOakes]

In the usual case, you need to source a stylesheet or write your own. Writing a stylesheet is not a trivial task.

If you have a FOSI file, this should be usable as a stylesheet in Arbortext. You can either select the stylesheet from the menus, or associate the stylesheet with the DTD (so that the stylesheet is automatically loaded). The way to associate the stylesheet with the DTD is to make sure they have the same name (eg. mil123.dtd and mil123.fos) and put them in a doctype folder of the same name (eg. mil123). You may need to setup catalogs for the public IDs.

BTW, our company (www.gpsl.co) has been working with the 38784 DTD for the US Army, and we supply services relating to that such as Arbortext development/training and XML/SGML software setup and configuration.

[GigiShep]

Can you use a DTD or FOSI to generate a DCF?

[GarethOakes]

You are meant to use Arbortext Architect to setup the DCF, but you can also edit the file in Arbortext Editor as it is just a markup file. The DCF is separate from the DTD, in that it describes how Arbortext should work with the DTD. The FOSI is the description of how the DTD elements should be treated for screen or print display.

[SuzanneNapoleon]

Typically, a revised DTD includes a section describing modifications since the previous release. This is where context problems will occur.

The TDT is a tag description table that describes the elements and attributes in the DTD, including any new ones.

The .fos file is the stylesheet, although it remains to be determined if it is for authoring, publishing, or both.

A DCF (doctype configuration file) is used to provide information about DTD elements and attributes, such as:

- whether an element should be treated as a graphic, paragraph, title, list, or division

- whether an element should be ignored during spell checking.

- what context tranformations are allowed, such as changing <section> to <chapter> when a <section> is moved from within a chapter to where a chapter is allowed.

And much more. You definitely need a DCF file. Arbortext Editor Help provides complete information on setting it up.

It seems like you should already have a .dcf file for the existing DTD. If so, it needs to be updated to reflect the new DTD changes. If you do not already have a .dcf file (doctype configuration file), perhaps you have an .atd file, which was its previous incarnation.

All that said, your existing documents will still be out-of-context with the new DTD. How seriously depends on the extent of the changes. You can use the links in a completeness check dialog to manually correct context problems, but in some cases that can be very time-consuming. ACL, XSLT, and other scripting can be used to automate the process. Others can provide real-world input on that.

BTW: In Arbortext Editor, select Tools->Preferences and click the checkboxes to show all warnings. Below that, select Errors, Warnings, and Informational messages to be displayed. Check the messages to see if any files or functions are not being found -- you probably need them.

[RayStachowiak]

Hi Jillian,

The answers provided Suzanne are pretty spot on. We do work for the Army truck vehicles and use 40051-2. The army provides us with a delivery package which contains the DTD, FOSI, DCF, and XSL stylesheets. The 40051 is in workpackage modular form so the dcf is fairly simple. I suspect if you go back to where you downloaded the DTD from then you may find a dcf file. It would be very difficult to create a DCF if you did not know the DTD and the document structures (styles) very well (personnel opinion here). We get that all supplied so hopefully if the AF provides the FOSI they probably have the DCF too. If you are using SGML DTDs you will have to compile them, for XML you do not. Also you will need a catalog file so that you can link the public identifier (used at the start of the doucment) to the DTD. Again they might provide one you can modify.

If you have been running this project alread you might already have most of this updated you will just need to replace the old with the new.

The best to you.

[GigiShep]

Thanks Gareth, Suzanne, and Raymond for your input. It was very helpful, as was the PTC support team.

Here is what happened in my situation:

[Short version = Use the v6 set of files with v9 DTD to see what happens; proper solution would be to obtain or build a v9 stylesheet, which, in this case, would have probably only a few differences from v6.]

Long version:

When trying to use the new DTD, Arbortext Editor prompted me to compile the DTD.

This process returned an error:

[A20082] Cannot create or write to temporary file C:\Program Files (x86)\Arbortext\Editor\custom\doctypes\38784STD-BV9\_catpath. Unable to compile the DTD.

The error was resolved by running Arbortext Editor as an administrator.

Compiling the DTD generated these files:

38784STD-BV9.dec

38784STD-BV9.log

38784STD-BV9.pro

38784STD-BV9.ptd

dtgen.log

...within the custom\doctypes folder for v9. Also present were the v9 DTD and .fos that I had obtained from the AF.

I had been informed that the compiling process would generate a demo file but it didn’t appear to.

At the suggestion of PTC tech support, I copied demo.sgml from my older custom directory (v6) to the new one (v9). I changed v6 to v9 within the file’s text, using Notepad.

I also copied “catalog” from v6 to v9, and again changed v6 to v9 within the file, using Notepad.

Same for template.sgml though I am not sure that file was needed.

And for the stylesheet (.style), I copied v6 to v9, and changed 6 to 9 within both the filename and the text of the file.

The reason to copy these v6 files to v9 was because at that point I just wanted to be able to open an sgml file using the v9 DTD regardless of whether I had the other proper v9 custom config files in place.

When I opened this “v9” demo.sgml in AE it gave me only two context errors.

From this point I was able to successfully associate my v6-compliant sgml document with the v9 DTD instead, and I print-composed using the v6-renamed-as-v9 stylesheet, which, while not technically correct process-wise, produced a correct-looking PDF, and this whole process basically served as a teaching tool.

I then had further questions about some specific tags which I wasn’t able to control in the way that I thought I should be able to. (Though admittedly these were tags & elements that I hadn’t used before.)

The PTC support person looked at the custom config files mentioned above, and asked for the DCF as well. Again, I only had a v6 version, within which we simply changed the v6 to v9, per his suggestion, and copied to the v9 directory. He wasn’t able to resolve the inoperability of the tags in question. Regardless of that issue (or in part because of?) he stated that the solution going forward would be to obtain or build a v9 stylesheet for this MIL standard (as Gareth had explained above, I believe) though the v6 version could be used in the meantime.