Upgrading Stationery Overrides
Version |
Date |
Changes |
1.0 |
2009-03-25 |
Initial version. |
Description
A brief overview of how to upgrade your stationery overrides
Simple overview
Welcome to the fun and exciting world of upgrading stationery!
Get yourself a diff tool. (I use Kdiff - http://kdiff3.sourceforge.net/)
- If at all possible, get a sandbox computer or something. (i.e. have your working stationery and working eP somewhere until you iron out all the details.)
- Install the new version of eP Pro.
- Point your new eP Pro at your old stationery project.
- Compare your overrides with the source files.
For example, I use DITA and WebWorks Help 5.0: I compare my override: <project>\Formats\Adapters\xml\scripts\dita\xsl\generate-xml\paragraph.xsl against C:\Program Files\WebWorks\ePublisher Pro\Adapters\xml\scripts\dita\xsl\generate-xml\paragraph.xsl and <project>\Targets\HostedHelp\Files\wwhelp\wwhimpl\common\scripts\controls.js against C:\Program Files\WebWorks\ePublisher Pro\Formats\WebWorks Help 5.0\Files\wwhelp\wwhimpl\common\scripts\controls.js You'll probably want to compare some whole directories, and some specific files.
- You'll find a lot of differences. You'll then need to merge the files. This can be as simple as going "oh look, they added six lines of code in the same file, but it's over here, completely separate from my overrides, so I'll just copy in those six lines into my file." or "Yes, I know my company logo graphic is different, I'll just ignore that." or "I enabled the mark of the web, so all my *.htm files are different. I'll have to compare each file manually to see if there are any other changes."
Every now and then, changes to the target format includes changes to the area where your override is. That may take some tinkering to get your override to work with the new changes.
That should get you started.
A few hints:
Keep notes! - Document what files you override, where, and why. This helps in many ways.
- You get a checklist of what files you need to compare whenever there's new Stationery
- You will forget why you did something, which makes upgrading harder.
Add comments in any file you override for yourself - If you just make changes in the files with no notes as to what are your edits, when you compare new versions, it will be harder to figure out what is your edit and what is a change from the Webworks side.
Refer to the page(s) in this wiki that describe all the changes between releases (e.g., http://wiki.webworks.com/HelpCenter/Tips/ChangedFilesIn2008.1).
When you add overrides, never add more files than necessary -- otherwise you'll have to diff them next release.
When an overrides file is no longer needed, delete it -- otherwise, you'll have to diff it next release.