This project has moved and is read-only. For the latest updates, please go here.

Specifying a presentation folder relative to a project path

Topics: User Forum
Jan 2, 2014 at 11:10 AM
For my Noda Time open source project, I want to use a custom presentation style so I can include extra tags etc. I would like the presentation style itself to be part of the project - or at least my modifications.

I've got this working using a NodaTime.presentation file which has a hard-coded path to the custom style, but I'd really like it to be relative to the project file, so that anyone can build the documentation. I've looked for a path property which indicates the project file's directory, but I haven't found one yet... does such a thing exist, and is it usable within a .presentation file?

Additionally, what's the licensing situation with regards to styles? I could potentially store just the changes in source control, and write a short program to create the full style from the installed ones and my changes, but that seems a little clumsy - can I include (in source control) the whole custom style which was copied from a standard one?
Jan 2, 2014 at 11:58 AM
I've just tried using {@ProjectFolder} in the PresentationStyle element, like this:
... but it looks like that's not being resolved:
Could not find a part of the path 'C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\{@ProjectFolder}\SandcastleStyle\SharedContent\NodaTimeBuilderContent_en-US.xml'.
Jan 2, 2014 at 12:07 PM
Okay, some progress - if I set an environment variable first, that works... but an explicitly set MSBuild property doesn't.

This does give me a way of building from a command line script - it's just not terribly pleasant in other cases.
I'll probably create a small tool to generate the whole style folder based on what's already installed, so I can easily keep up to date with any other presentation changes.

If there's a better approach to all of this, I'm all ears :)
Jan 2, 2014 at 5:20 PM
I've had a couple of requests for project-specific presentation styles. In the current release, it only looks in the SHFB installation folder and the program data folder for custom presentation styles. I'm making changes for the next release that will make it easier to have project-specific plug-ins, build components, and presentation styles. It will look in the standard locations as well as the project folder or a path pointed to by a new Component Path project property.

Plug-ins, build components, and syntax generators have already been converted to a MEF-based implementation for the next release to get rid of the magic file extensions and configuration files. I'm considering taking a similar approach for the presentation styles: a component assembly containing the definition which would be distributed with the files that make up the presentation style. That would allow managing and building the presentation style as a Visual Studio project too. Testing would be easier as well since you could create a test SHFB project within the same solution that references the presentation style project output via the Component Path property to try it out. My plan is to have the next release out in about three weeks or so.

With regard to licensing, everything is distributed under the Ms-PL license so you are free to copy the files and create derived works as you see fit within the terms of the license. If you think your changes are useful to all users in general, feel free to contribute them to the project for inclusion in a later release.

Jan 3, 2014 at 8:27 AM
Thanks for the response. Sounds like what I've got at the moment is appropriate, but that your changes may well help me clean things up soon.

As for whether what I've got is useful to other projects - it's probably too early to say. The only change is similar to what "Version Builder" does, except that I only want to list the earliest version a member appeared in, and whether or not it's in the PCL version. See for sample output.