Creating a new document from the Welcome screen, doesn't

Report · Apr 16, 2019

I think this must be really simple but I can't see the problem.

I've defined a structured application with DOCTYPE, DTD, Template, read/write rules, pre- and post-processor stylesheets.

I can open an existing XML document and everything works.

On the Welcome screen under "Create a new document" there is a button labelled "<xml/>" with the name of my application, and lots of other buttons indicating document types in other structured applications.

If I click any of the other buttons, Frame opens either an empty or trivial document, called "UntitledN.xml", and sets the structured application to that appropriate to the button I clicked.

If I click the button corresponding to my application, nothing happens.

I can't see any relevant difference between my application and the others - both have paths provided to template.fm documents (which exist), DTD and so on.

Can anyone help me here please?

Cheers,

T

Report · Apr 16, 2019

Trevor,

Try the "... Other XML" button rather than the "<xml/> Empty XML" button. "Other XML" lets you choose an application. "Empty XML", which was available in FM 2017 but is gone in FM 2019, creates a new document with only one element defined: <ROOT>. In code view, you can add additional elements.

--Lynne

Report · Apr 16, 2019

Hi

Actually I tried going through "other XML" > Structured Applications > myapplication first (which also appeared to do nothing at all), and then noticed that there was a button at the top with myapplication and empty XML. I assumed Frame had added that button because I have been editing other documents in my application.

I only noticed this problem because I was trying to explain how to set up a new FM user - my notes (which started with an older version of Frame) said "use Edit > Preferences > General to set your product interface to 'Structured Framemaker', and then use Structure > Set Structured Application to set the application to 'myapplication'". It turns out that this second step is only possible if you already have a document open, i.e. you can't do it from the welcome screen. So how do I create an empty 'myapplication' document? Apparently I can't - but it ought to be possible because Every Other Option in the Structured Applications list opens a basic document when selected. Mine is the only application which doesn't. So I've evidently got something wrong, but the documentation isn't helping me find what that is!

Report · Apr 17, 2019

Trevor,

To answer the side question fist, Set Structured Application sets a document property. It can't be used from the welcome screen because the welcome screen is not an FM document. Associating an application with an individual document allows you to have multiple documents open without requiring them all to use the same application. An application can be set in a document either with Set Structured Application or with the StructuredApplication element in an EDD. Since a template is just an FM document, setting the application in a template preserves that setting in each document created from that template.

To get back to the main issue, the Other XML button on the welcome screen brings up the New XML dialog box, which has 4 tabs:

1. Recently Used let's you choose to create a new document from an option you have recently used.

2. Structured Applications lists a subset of the currently available structured applications. In particular, it lists XML applications that define a template and specified template exists. The list changes each time you Read Application Definitions.

3. DITA lists only DITA applications.

4. Other XML gives you a choice of Empty XML, which creates a document consisting of only a ROOT element, or DTD-based XML, which lets you edit an XML document conforming to a DTD that you specify. The DTD-based XML will not have any formatting associated with the various elements you ceate.

In your case, you want to choose Structured Applications. If your new application is not listed, make sure that you have added the application to your application definition file (probably %appdata%\Adobe\FrameMaker\n\structapps.fm), where n indicates the version of FM you are using. Remember that FM reads application definitions from the file in %appdata% when it starts. If you have changed this file, of if you are using a different file, you'll need to read application definitions before you use the Other XML button. If you are sure FM has processed the correct application definition file and you still don't see the application listed, make sure that the template is defined in the application, and the file exists.

--Lynne

Report · Apr 17, 2019

Hi Lynne

Thanks for your answer. You're very thorough (I remember that from a few years ago when I was using FM7 for a similar project)!

First the side question, thank you, that makes sense. And the correct structured application has been associated with my template.fm because that's what the Structure > set structured application dialog offers me when I open the template and take that option. It's also the application shown when I open any of my existing XML files. So that's all good.

When I start Frame and look at the welcome screen, I see a set of buttons for XML documents and below that a set for Frame documents. As per your instructions (and this is what I did the first time before posting this question) I click Other XML, which gives me a New XML dialog where I can pick Structured Applications to see a list of apps defined in structapps.fm. My application is in there, at the bottom of the list. I highlight it and click OK. The dialog closes and Nothing Else Happens.

I can also see the application in Recently Used and the outcome there is the same.. "Nothing happens."

The application is there in structapps.fm, and the template it defines exists. (Your answer implied that if either of those were untrue, Frame wouldn't have included the application in the list, but it does.)

I can see nothing wrong with the template - I can open the template file directly using File > Open and it is associated with my application and contains all my element definitions.

The other way to open a new document is to go File > New > Document and select my template.fm as the template to use. When I do this I see a new tab which is labelled Untitled.fm (not Untitled.xml, which is what I believe it should be, based on how the other applications appear to work). The structure view does not appear (it does if I open an existing XML document), but the element catalog is offering me the correct elements for my schema, so it's using the right application. When I save the document the option of saving as XML isn't offered.

So the application's mainly there, but something crucial is missing. I just can't see what.

Cheers

T

Report · Apr 18, 2019

Trevor,

1. What version of FM are you using? Is it fully updated? Have you recreated %appdata%\Adobe\FrameMaker\n? To do so:

a. Close FrameMaker.

b. Rename the original folder.

c. Restart FM to create a new folder of the original name.

d. Close FM.

e. Copy maker.ini and structapps.fm from the saved original folder to the new one.

2. In your application definition file, is the location of the template specified with an absolute path? If not, New XML may be looking for the template in the wrong folder.

3. What happens when you create a new application that uses the same template as the problematic application? Does it work differently than the original application?

4. When you use File > New > Document to create a new file from a template, the new file does not exist until you save it. It appears in a new window titled Untitledn.fm because the new material was created from an FM document. You can specify a different type of file when you actually save it which may cause FM to change the extension. When you open an existing XML document in WYSIWYG view, FM remembers that the resulting formatted FM content originated as XML, preserves the xml extension in the window title and converts the content back to XML when you save. Thus your comment about seeing Untitledn.fm and Untitledn.xml depending on how you create a new document makes sense to me.

5. Whether or not the Structure View and various other pods open when you create a new document depends on the active workspace. In particular, unless you edit the workspace, the Structure View opens with XML/Structured but not Authoring. When you close FM, it saves the current workspace in the LastUsedWorkSpaceInStructuredMode setting in maker.ini.

--Lynne

Report · Apr 25, 2019

Hi

1. I am using version 15.0.2.503 of the 2019 release. As far as I know it is fully updated. It also has a newer version of the Saxon JAR file which Adobe support sent me; this has not yet made it to the official release, but I believe it will in time. This was required because our pre- and post-processor stylesheets were failing when run within Framemaker although Saxon would run them fine in a normal operating environment. The new JAR file addresses this.

When I inspect the contents of %appdata%\Roaming\Adobe\FrameMaker\15 I can see a structapps.fm which is empty apart from the initial note and the version number (15.0). I scanned the maker.ini file for anything interesting but nothing stood out.

Recreated the folder as per your instructions anyway.

Now when I go Other XML > Other XML > MyApplication in the welcome screen I get an untitled.xml window. It thinks it's editing a structured document, but it hasn't set the structured application correctly. I have to go Structure > Set structured application and change it to my application. When I do this an error appears in the console telling me that it can't find \myapp.dtd. OK this is a potential problem.

2. "All the paths in the application definition file are absolute."

I was sure that was true but I've just discovered that it isn't. The DTD is relative. I'm not convinced that this is the root cause of my problem, because recreating the appdata folder has changed the behaviour slightly and allowed me to open an empty XML file rather than an FM, which is a step forward.

The DTD is relative because in the normal functioning of the application the DTD is adjacent to the documents folders, and I can't dictate where those might be. But when the user saves the XML document somewhere we need the path to the DTD in the XML header to be a relative path to the correct DTD. Unfortunately the relative path is rubbish when Frame is working with a brand new document that has no path. Not sure what the correct solution is here.

3. I haven't tried this because I've just identified the problem described in 2.

4. Thanks for this explanation.

5. I figured a lot of that out when I scanned the maker.ini file in appdata. For normal operation I'd like to see, from left to right: the WYSIWYG view, the Structure view, the Element pod and the Attributes pod, and the console. Right now I'm looking at the first 4 but I'm blowed if I can see how to make the console visible. It's probably obvious but I've missed it.

cheers

T

Report · Apr 25, 2019

I wouldn't expect it to resolve your issue, but 15.03.603 is the latest release (released on or about Mar 29th)

I'd suggest updating just in case this was fixed.

-Matt Sullivan
FrameMaker Course Creator, Author, Trainer, Consultant

Report · Apr 25, 2019

Trevor,

1. Yes, take Matt's advice an update to Patch 3.

2. I will get back to you shortly on the issue of the pathname of the DTD.

5. Open the console with View > Pods > Console or Esc c P.

Remember that later versions of FM provide Command Search, invoked by F7, the magnifying glass a few symbols to the left of the upper right corner of the main FM window, Ctrl-Shift-S, or View > Command Search, which lists commands whose names include a string you type. For example, typing "Console" into the Command Search window shows how to open the console pod.

Anyway, once you have a window arranged the way you anticipate using most often, select Save workspace from the workspace pull-down menu next to the name of the current workspace in the upper right of the main FM window. (Unfortunately, Command Search doesn't find the workspace commands!). FM will prompt for the name of this custom workspace.

--Lynne

Report · Apr 25, 2019

Trevor,

a. You say you use Other XML > Other XML > MyApplication. Please clarify. In particular, if you click the Other XML tile on the welcome screen, the New XML dialog box appears. If you choose Structured Applications in the left pane, you can then choose an application called MyApplication in the right pane, provided that MyApplication defines a template with an absolute path. FM will then create a new file from that template. If an application has been set in the template, that application will be set in the new file.

If instead you choose Other XML in the left pane, you can then choose to create an XML document from your DTD, In this case, you have not chosen an application so the new XML document will not use your application and no application will be stored in it. The document will have element definitions derived from the DTD but those element definitions will not have any format rules.

b. You are specifying a relative pathname for the DTD because you don't know where you users will store the DTD. Unfortunately, FM must be able to find the DTD to properly read or write XML.

i) When you open an XML document where the DOCTYPE declaration specifies a relative path, FM will look for the DTD in the same folder as the document it is opening. If it can't find it there, it will search in the folders specified in the entity search paths in the application definition, Thus, the application must either specify an absolute path or one or more folders where the DTD might be found.

ii) When you save an XML document, by default FM starts with a DOCTYPE declaration with a relative path if the document and DTD are in the same folder and otherwise with an absolute path. (You can suppress the DOCTYPE declaration with the r/w rule: "writer do not include dtd;")

You say the DTD is always adjacent to the documents. Does this mean you can determine the absolute path of the DTD from the path of the documents being processed? Since you are using pre- and post-processing, you might be able to use XSLT to change between

absolute and relative paths. When you open an XML document, your pre-process can retrieve the URI of the input document and use it to

generate a new DOCTYPE declaration with an absolute path. If you are saving XML documents to a folder that contains the DTD, FM should generate a relative pathname and you should be OK without a post-process.

--Lynne

Report · Apr 25, 2019

Thanks for the workspace help, awesome. I'm much happier with the layout now. It would be cool if layouts could be saved and shared with colleagues but it's easy enough to walk someone through it.

I'll definitely install the latest update but I need Adobe to get back to me on the status of the Saxon JAR file that comes with it. If it's the same as the custom one they sent me that's great. If it has other fixes but not ours, that's bad!

Now the pesky DTD problem. First, this is our normal file structure:

Application_Home > xml_utils > ( app.dtd, app.xsd, fmapp.dtd, ... )

Application_Home > documents > doc_code > ( doc.xml, intro.xml, stuff.xml, ... )

On loading into Frame we had to make some element changes involving tables, graphics and cross-references, so the pre-processor does this, and also modifies the document header. Before loading into Frame, the documents all contain a header like this:

After passing through our pre-processor XSL this is changed to this:

<!DOCTYPE document SYSTEM "../../xml_utils/fmapp.dtd">

and the post-processor makes the equivalent change back.

This all works absolutely fine when we are dealing with existing documents in our file system. It breaks badly with a "new" document.

I think I've just proved that because the FM DTD is only used for the processed version of the document that Frame loads, it can certainly have an absolute path, and I'll be trying that right now 🙂

I'll show what happens when trying to load a new document in the next reply.

Report · Apr 26, 2019

Right. Sorry this is long. I've also used screen captures so I can't use generic names for the files and application any more 🙂

I have copied the DTD into the app directory and changed the application definition in structapps.fm so that every file has an absolute path:

(There's no post processor stylesheet in the definition because our post stylesheet crashes Saxon in FrameMaker, although it runs fine invoked in a normal shell. So, for the moment, we save the document as XML and run the post stylesheet separately.)

Changing the DTD to a fixed location has not affected our normal workflow when editing existing XML documents. And I wouldn't expect it to because the XML headers are constructed by our stylesheets.

But this thread is all about trying to create a new document before deciding where to save it. And that's still not quite working.

I start FrameMaker and get the Welcome screen, where I select "Other XML" in the "Create a New Document" pane:

This opens a New XML dialog with four choices in the LH panel: recently used, structured applications, DITA, other XML. I pick Structured applications and the RH panel allows me to pick from all the apps which are defined in structapps.fm. My app is at the bottom of the list:

I click OK and the cursor turns into an hourglass for about a second before reverting. No other windows change, no new document is opened, there is nothing reported in the console. FrameMaker tried to do something but it didn't succeed, and it didn't tell me what went wrong.

Right. Let's try the other route. From the Welcome screen I go File > New > XML. This puts up the same New XML dialog with the same second's brief activity and (lack of) result.

Last option: File > New > Document. Now I see a dialog which allows me to pick a template, so I select the template file defined for my app in structapps.fm:

When I click "New" I do get a new document window; the document is labelled Untitled1.fm, and the element pod shows me the correct elements.

(This wasn't working when the DTD path in the app definition was relative; it reported a problem in the console. Now it's working.)

At this point I can insert content into the document and if, when I save it, I save it as XML in the correct part of the filesystem, it will be valid. I need to run the post-processor stylesheet to remove

<!DOCTYPE document SYSTEM "file:///C:/Program%20Files/Adobe/Adobe%20FrameMaker%202019/structure/xml/helpcenter/app/fmdocs.dtd" [ ]>

and add the xsi namespace and xsi:noNamespaceSchemaLocation="../../hcdocs.xsd" attributes to the document element, but the stylesheet already does that.

So this last method is almost there.

Minor question: given the template is associated with the correct structured app, why couldn't the document be opened as an XML?
Major question: why doesn't the New XML dialog from the welcome screen work? (perhaps that's the same question)

Thanks for reaching the last line of this!

Cheers
T

Report · Apr 26, 2019

Trevor,

1. Thank you for providing more details on your workflow. Once I realized that you were using a preprocess, I was able to duplicate the problem with a simple test case. Other XML does not create a new document when the selected application has a preprocess. No error messages appear in the console. I will file a bug about this problem.

2. Just because your template has set a structured application does not mean you will never save documents as FM file.

3. The following observation won't help you create new documents with the .xml extension in the tentative filename. Nevertheless, my own preference is to see the .fm extension. I strongly recommend saving working documents as FM. When you are editing in WYSIWYG view, you are working with an FM document. When you save it as XML, FM uses the XML application to convert the WYSIWYG structure to XML. If the document is invalid, if there are errors in the DTD, r/w rules, or postprocess transform, or even if there is content that is used only within FM, content could be lost in the XML version. Similarly, when you open an XML document, FM uses your application to interpret the XML and create a WYSIWYG document. Any problems with the application can result in lost content. Once the document is complete and the application has been thoroughly tested, you can save it as XML.

4. By the way you can get to the New XML dialog box without going through the welcome screen with File > New > XML or Esc f X.

5. In situations when you do successfully create a new document from the Other XML tile on the welcome screen, FM adds a new tile to the welcome screen for the selected application. This convention saves you from going through New XML to create multiple documents using the same application.

--Lynne

Report · Apr 26, 2019

Hi Lynne

1. Great that this exercise has identified a bug. It's also taught me a lot.

2. OK. We never will, but I can see that others might.

3. All our documents are published to the web through XSL / HTML / CSS. Frame's formatting facilities are largely superfluous to our needs (although the EDD I maintain tries to approximate the same appearance for the WYSIWYG editing). Structured Frame might seem like overkill for us but it has been much better than alternative XML editors we have tried, for substantial editing at least. We do use other tools when we are just tidying up and correcting typos.

5. The "new" helpcenter tile is on my welcome screen, but of course it has the same problem as the other pathways to a new XML.

Thanks very much for your assistance.

Cheers, T

Report · Apr 26, 2019

Trevor,

Sorry, but I need to withdraw my claim that I had confirmed a bug. My initial test specified a relative path for the preprocess transform. When I change it to an absolute path, FM does open a new window.

It's interesting that FM seems to require that the specified stylesheet exists, since it doesn't seem to run it. When the path is correct, I get a new untitled document containing a single element, whose tag is that of the first highest-level element declared in the EDD. The preprocess would have inserted a subelement containing some text into that element, and that does not happen.

--Lynne

Report · Apr 28, 2019

I guess in your example there's no file for the pre-process to use as input, so not seeing your sub-element makes sense.

But you are at least seeing a document, and I'm not!

Report · Apr 29, 2019

Trevor,

At this point we know that:

1) You can use the New XML dialog to create new XML documents for some applications but not for yours.

2) FM does not report an error when it fails to create a new XML document, at least when the failure is due to its inability to find one of the application files.

If I were in your situation, I would compare the failing application to a working one. I would make a small change to one or the other repeatedly until the behavior changed which would give me a clue about what the significant difference might be. For example, can you create a new XML document if you remove the pre-process from your application? If so, the pre-process is not the problem, so continue your debugging without it. If not, what if you use a simpler pre-process? Is there content (such as sample text) in your application's template? If so, what happens if you delete that content?

I did my testing using an application based on the simple DTD:

<!ELEMENT document (paragraph)+>

<!ELEMENT paragraph (#PCDATA)>

I opened it to create an EDD and FM set the first element type (document) to be valid at the highest level. I didn't add any format rules and imported element definitions from the EDD into a new portrait document and saved that file as the template. I defined an application that specified the DTD, the template, and a simple pre-process that simply adds a new paragraph containing a few words at the beginning of a document. The latest version of the application does not use r/w rules. What is the significant difference between my application and yours?

If you create a similar application, does New XML create new files from that application?

--Lynne

Report · May 05, 2019

Hi Lynne

Sorry for the delay responding, I've had to pay attention to a few other things before I could return to this. I've decided to rewind a long way and implement this a little differently. You may have noticed my other post about putting application definitions under source control - doing this requires too much monkeying with permissions in the Program Files for my liking, so I reread the developer's guide and decided that I should relocate $STRUCTDIR so that it isn't in a protected location.

SO... I have edited maker.ini so that it now contains the line

StructureDir=C:\Users\tcn\.....\framemaker_files\Structure

where that Structure directory contains everything which I was telling my users to copy into the FrameMaker installation area:

...\Structure

(contains structapps.fm)

...\Structure\xml\helpcenter\app

(contains docs.dtd, docs.xsd, fmdocs.dtd, hc_edd.fm, doc2fm.xsl, fm2doc.xsl, rules, and template.fm)

I started FrameMaker, and went to Structure > Application Definition > Edit Global Application Definitions from the menu. I added a new XMLapplication named "testing" and saved the definitions, then checked in the filesystem to see that, yes, the source controlled version of structapps.fm had been modified.

Then I exited FrameMaker and reloaded it.

As far as I can tell everything is working, although in this configuration Frame seems to be creating img1.mif, img2.mif files which it wasn't before. Where might they be coming from? None of my application definitions or the files referenced in them refer to MIF at all, and I've never seen MIF files created in the past.

Anyway, tomorrow I'll slowly stepwise bring the testing app into line with helpcenter and try to discover at what point the New document fails to appear.

Thanks for joining me on this saga...

Cheers

T

Report · May 08, 2019

Hi Lynn

So I have a little testing app, just like yours.

First, I'd just note that I have made two changes to the installed maker.ini file:

RemoveExtraWhiteSpacesOnXMLImport=Off

StructureDir=C:\Users\trevor\doco\current\framemaker_files\Structure

So here's my DTD:

And here's the EDD:

I created a new template, imported the element definitions from this EDD, and saved it as template.fm in the same folder.

The structapps.fm file (at the path shown in maker.ini above) currently contains everything that came in the installed structapps.fm file, plus my helpcenter and testing applications. I should probably purge all the applications we don't use because I haven't copied across all the ancillary files that structapps references for them, but I don't think that's relevant to this problem.

So here's the testing app in structapps:

With these definitions, I can open FrameMaker, pick "Other XML" from the welcome screen, pick "Structured applications" > "testing" from the New XML screen, click "OK", and a new document (Untitled1.XML) is opened, containing a document node.

Right. Now let's add a preprocessor step.

Here's the modified structapps:

and this is the stylesheet test.xsl:

With this modification, the New XML procedure above shows a brief hourglass cursor, then does nothing. There are no errors reported.

Just for completeness, I removed the pre-processor step, created a document through New XML and saved it:

then put the pre-processor step back and opened the document I had just saved, showing that the pre-processor runs fine (there is a warning about being unable to validate because there's no path to the DTD in the file, that's because I kept the test.xsl as minimal as possible):

So it's clear where the problem is, but not what it is.

I'll close this post here and pick up in the next one.

Report · May 08, 2019

Resuming.

When the pre-processor stylesheet doesn't specify the path to the DTD to use on the intermediate XML file, FrameMaker issues a warning. This shows that, in the pre-processing stage, FrameMaker does not use the DTD referenced in structapps.fm ($STRUCTDIR\xml\testing\apps\test.dtd) but requires that the intermediate XML file explicitly specify one.

I can modify my test.xsl to do this, but the path has to be complete.

Specifying "test.dtd" and assuming it will be found either in the current directory or in the path does not work.
Specifying a relative path from where the document exists (which works when opening existing documents) does not work.

This is because FrameMaker creates the intermediate XML file somewhere in the user's AppData and test.dtd is not there or in the relative path from there. (For some reason relative paths work with existing documents though.)

Thus:

With this change, opening existing XML documents gives no warning, and opening a new document succeeds!

So we're left with a problem. The path to the DTD in the screenshot above is the same as the effective path given in structapps.fm, but it has to be specified; Frame isn't using it by default. It can't be specified the same way as it is in structapps.fm, because we don't have $STRUCTDIR to expand. We can't just insert a constant because $STRUCTDIR is different for different users. A relative path works for existing documents but not for new ones.

What do you think? Should the pre-processor even be executed when creating New documents? Should FrameMaker use the application DTD if the input file doesn't specify one? Is this such a rare situation that it should just be noted and ignored?

Report · May 10, 2019

Trevor,

This discussion has moved away from the original topic of creating new XML documents from the welcome screen. I am going to start some new ones on some of the issues you mention. I will try to finish by the end of this weekend.

--Lynne