Skip to content

Latest commit

 

History

History
90 lines (85 loc) · 5.86 KB

UPGRADE.md

File metadata and controls

90 lines (85 loc) · 5.86 KB

Upgrading

Upgrading Guiguts involves installing the new version in a directory and possibly copying a few files over from the prior install. This document walks you through all the steps.

This document assumes you have Guiguts installed in c:\guiguts. If you have this installed in a different location, you will need to adjust the paths below accordingly. Despite the instructions using Windows paths, the overall steps below work for all operating systems.

  1. Backup your old installation. It is highly recommended that you backup your prior Guiguts installation before continuing.
  2. Rename your old Guiguts directory (eg: c:\guiguts) to a new one (eg: c:\guiguts-old).
  3. Follow the instructions in INSTALL.md to install Guiguts for your operating system, including any helper applications, noting that if you are upgrading from release 1.0.25 or earlier on Windows, you must install Strawberry Perl before trying to install and run Guiguts. Note the requirement to run install_cpan_modules.pl to ensure all necessary Perl modules are installed.
  4. Review and possibly copy over changes made to Guiguts files.

    • This release has two features that will assist with this process for the current release and largely eliminate this step for future releases. It is therefore recommended that you complete the following steps if you have never done them before:

      1. Run the newly installed Guiguts program, open the Preferences menu, then File Paths, then select Copy Settings From A Release. Use the dialog that pops up to select the top level of your old release (eg: c:\guiguts-old). This should be a folder that contains guiguts.pl, headerdefault.txt, etc. Using this option will copy necessary configuration files from the old release into a new folder named %HOMEPATH%\Documents\GGprefs where %HOMEPATH% is your home directory, e.g. C:\Users\user1\Documents\GGprefs. The folder is similarly under your home directory Documents folder on a Mac. Under Linux, the new folder will be $HOME/.GGprefs. When you have done this once, you will not normally want to do it again when you upgrade to a future release, because all your settings will be safe in the GGprefs folder.
      2. If you have previously customized the header.txt used during HTML generation, it is recommended that you use the new header_user.txt feature instead. During HTML generation, if Guiguts finds a header_user.txt file, it will insert this into the HTML file just before the end of the headerdefault.txt file that was included at the top. This mechanism means that you will gain the benefits of any changes to the default header in future releases, while retaining your own customizations, which usually you will not need to alter between releases. To take advantage of this, create a file named header_user.txt in the GGPrefs folder created in the step above. Add CSS to header_user.txt to augment or override the CSS contained in headerdefault.txt. For example, if headerdefault.txt sets the width of the HR at the end of a chapter to 65%, but you prefer a width of 30%, you could add the following CSS to header_user.txt: hr.chap {width:30%}. Normal CSS rules apply regarding priority, so your customization will override the default.
      3. You will not need to apply the following bullet points regarding setting.rc, data and header.txt, since the relevant files are now safely in your GGprefs folder.

    • The setting.rc file stores Guiguts configurations. This file is automatically generated by Guiguts if it doesn't exist. Newer versions of Guiguts will include updated defaults, such as DP URLs and bundled tool locations. It is recommended that you do not copy this file from your old version but let the new Guiguts create the file afresh. You may then have some preferences you want to change within Guiguts which will be saved in this file.

    • The files in the data directory contain words used in HTML generation like Footnote and Page, so they can be customized for different languages. If you have changed these in the old release, copy the relevant ones to the new release. This will not apply to most users.

    • The file headerdefault.txt has had important changes made to it in this release. When you first run Guiguts, it copies this file to one named header.txt. If you have customized your header.txt in a previous release, you may want to retain those changes in the new release. If you are upgrading from a 1.3.x release, you can copy header.txt from the old release to the new one after you have run and exited Guiguts once. If you are upgrading from an older release, e.g. 1.0.25, 1.1.x or 1.2.x, you should follow the steps below to ensure you get all the updates:

      1. In the old directory compare header.txt with headerdefault.txt, making note of any differences.
      2. Run the newly installed Guiguts program to create the new header.txt then immediately exit.
      3. Edit header.txt in the new directory and make the changes you want to carry over from the old release.

    • If you were using @media handheld in your customized header file, please note that it is now deprecated. The same effects can be achieved using the x-ebookmaker class as described here. Alternatively, ask in the DP forum Help with: guiguts thread.

You can now run Guiguts from the new installation directory.