What files actually go in a project?

[tsurikov]

I've used Oxygen for a long time to edit DITA content, and am now investigating the project feature. It's well documented here, and I've read that entire hierarchy. And yet I still don't understand a very basic aspect of projects...

... What files actually go into an Oxygen project?

The first subpage in the above link says "Oxygen XML Editor allows you to organize your XML-related files into projects." I don't know what you mean by "XML-related files".

To be more precise: When I work with Oxygen without using the project feature, I have maps, topics, images, DITAVAL files, a DITA-OT installation with custom plug-in, the Oxygen configuration, and of course my Oxygen application itself. Are all of these "XML-related files" that I must add to my project? And if I add a file to my DITA content, must I also manually add this file to the project? (I hope not... that means I'd have to manage hundreds of files twice, manually!)

[Radu]

Hi,
In general I would recommend you create the "project.xpr" file directly in your project's folder. Automatically all your project's contents (including XML, images and all other resources) will be accessible in the Oxygen Project view.

For example for the Oxygen XML Blog project which is hosted on GitHub I created a blog.xpr file directly in the project root folder:
https://github.com/oxygenxml/blog

You can use projects to search for, open and work on your files, perform batch operations like Find/Replace in Files or validation. Also most of the Oxygen Preferences pages have a "Project Options" radio button at the bottom allowing you to save custom settings at project level.

In time you may create a custom DITA framework configuration, provide for example custom editing actions, new file templates and more. You may add a folder containing a publishing template. Or you may add a terminology rules folder. There are some examples listed here:

https://github.com/oxygenxml/DITA-Startup-Project

Regards,
Radu

[tsurikov]

Hi Radu, and thank you for the super-fast response!

You wrote "directly in your project's folder". That's what I don't currently understand. What counts as a project's folder, in this context? I have DITA source files scattered over ~20 folders, my DITA installation in C:\dita-ot, my custom plugin in a deep subfolder of that, and my Oxygen application in the usual long C:\users\...\AppData\... hierarchy. Which of those is "my project's folder"?

[Radu]

Hi,

In general we try to organize all our documentation in one folder which is a Git repository so that we can all check out the same folder and collaborate on it.
In the past when we had DITA OT customizations and plugins we even had the DITA OT folder as part of the documentation folder and committed it to the Git repository.

Coming back to your question you can either have multiple project.xpr files (multiple projects) saved in each folder and then switch between them in the Oxygen Project view or have a single project.xpr project file saved for example in the main documentation folder, load it in the Project view, then right click the project root and use the "Add folder" action to add multiple folder references to the single project. So the project.xpr project can refer to a variety of local folders and you will see them all at once and be able to expand and work with all these folders from the Oxygen Project view.

Regards,
Radu

[tsurikov]

Thanks very much, Radu.

With your last response, I now understand that I am free to define whatever files I want in an Oxygen project, and that projects support many different file types. This is really helpful. I am no longer confused.

Best regards always,
--Michael

[Radu]

Hi Michael
With pleasure, we'll also update our docs to state things more clearly.
Regards,
Radu