Where should I insert my custom XSL Transformation

May 9, 2014 at 5:10 PM
Edited May 9, 2014 at 5:11 PM
Hi everyone,

I created an XSL Transformation file so I can rename apis in the reflection info file.
(Sounds weird I know, but I need to display the members in a user friendly fashion while a new syntax generator will display the actual syntax to use. I'm modifying only the name attributes.)

I would really want to avoid creating a plug-in since it's time consuming and to my opinion an overkill for my isolated needs.

Question: Where should I put (in config files) or execute my XSL Transformation file.
I know sandcastle.config contains many of them but I refuse putting it there while not knowing if it`s appropriate.

May 9, 2014 at 11:40 PM
In TransformManifest.proj, there`s a BeforeTransformManifest target.
If I could just override it somehow so I can add my appropriate xlstransform task to it.

If someone could just spare me hours of research.
May 9, 2014 at 11:50 PM
You may not want to, but writing a plug-in is the appropriate solution. The other alternative is to manually add it to the project template but you'll have to do that with each new release and it would run for every project which is undesirable. The plug-in will allow you to add it to just the projects that need it. The new plug-in project templates give a good head start so it shouldn't take that long given the simplicity of the task at hand. See the ScriptSharpPlugIn for an example as it's close to what you want to do.

May 10, 2014 at 8:49 PM
Edited May 10, 2014 at 8:50 PM
Eric, I really think we should add a way to override TransformManifest.proj targets. Why not add a simple import targets statement at the end of the document that would load project specific targets? I wouldn't cost mush.

Adding a single transformation, especially as simple as mine, shouldn't require writing a cs class and creating a winform with all the configuration xpathnavigator hassle. Also, if I would create a plug-in, I wouldn't ever want to re-use it.

I think what I'll do is add a msbuild task in the BeforeBuildHelp target, that'll ensure the current version of TransformManifest.proj has the import statement and define my targets override in a project specific file.

I understand the plug-in logic, but when it's one time use only/not to be redistributed, small, I think that's an overkill.
Why couldn`t we specify target tasks for all the individual build steps?

May 10, 2014 at 8:56 PM
Edited May 10, 2014 at 8:57 PM
Something around those lines:
<Import Project ="$(WorkingFolder)\TransformManifest.targets" Condition="Exists('$(WorkingFolder)\TransformManifest.targets')"/>
The only thing that would that would left to do is to copy TransformManifest.targets when in project folder to the working folder.

Correct me if I'm wrong.
May 10, 2014 at 10:38 PM
The plug-in architecture exist to handle this. Sorry, but that is not going to change. If it's just a one-off, it doesn't need to be configurable, just hard code everything.

May 11, 2014 at 8:53 PM
FYI, I've implemented the import and a simple r-o copy of my targets file to the working folder and it works like a charm.
I've also added a task that adds the import element conditionally to follow SHFB updates.

It worth the effort as I might override TransformManifest targets in other projects, but still I fail to see the need of an overcomplicated plug-in.
Granted it would have been built-in, my action would have taken 5 lines of code only.

I'm sorry we disagree on this and I humbly invite you to reconsider.
At worst, why not add other event menus in SHFB such as the Pre and Post build event?
This arise the question: Why have pre and post build events if we're so plug-in driven?

I couldn't hardcode TransformManifest.proj in install folder as I am managing 5 SHFB projects.
I think we should be able to customize/overload all core operations on a per project basis
meaning without having to modify SHFB installation. E.g.: change a sandcastle transformation file for a single project.

This is just a friendly opinion.
Jun 19, 2014 at 8:59 PM
I agree with Olograph. I would be tasked with writing a plugin when all I want to do is suppress some output information by commenting out one set of lines from the utilities_reference.xsl file. This task would take me seconds, but learning the plugin creation process will take some time. Also, many folks using these tools are technical writers that will not want to write plugins.

Why not have a way to add transformation files to the project as you can do with cs files?