Setting up a Windows machine

Short version

  • Download Frogdown.zip and unzip it in C:\FrogTemp
  • Create C:\home Copy the bin, etc, frog_authoring, and WindowsOnly folders to C:\home.
    Copy C:\home\WindowsOnly\bin to C:\home\bin.
  • Download and install ActiveState Perl. Makes sure that Perl is on the path.
  • Download and install ImageMagick Make sure that convert.exe is on the path.
  • Add C:\home\bin to the path.
  • Add FHOME=C:\home and PERL5LIB=C:\home\bin\perl5lib environment variables.
  • Copy site specfic files from C:\home\etc\markcms-windows to C:\home\etc\markcms Maybe look at them.
  • Go to C:\home\WindowsOnly\bin and run
    IsPerlHere.bat
    IsImageMagickHere.bat
    TestPerl.pl
    ShortDemo.bat
    Check that none of them complain. If so, then fix any problems that are reported. Maybe skim the rest of the page.
  • Look over the Intro to Frogdown
  • Check out Making it GUI

Long version

We go into a bit more detail. In case the above was too cryptic.

I use ActiveState Perl so all my directions are about this version of Perl. If you use some other version of Perl, than adapt as needed.

Getting the files

Temporary directory where<br>you unzipped Frogdown.zip
Temporary directory where
you unzipped Frogdown.zip

Download the zip file to a temporary directory Create a directory (say, C:\FrogTemp) and download Frogdown.zip to it. In Windows Explorer, navigate to C:\FrogTemp and unzip Frogdown.zip

Create the 'home' directory We use Linux/UNIX conventions and use a home directory. To increase the odds of this working right off the bat, create C:\home. The rest of these docs will assume that this is what we are using.

Copy the files to where they belong Open two Windows Explorer windows. Have one in C:\FrogTemp, the other in C:\home

C:\home\WindowsOnly\InstallTests
C:\home\WindowsOnly\InstallTests

Copy Windows only files (This zip file is also for UNIX/Linux and contains several files that are only applicable for Windows PCs) In the FrogTemp folder, change to WindowsOnly\bin In the C:\home folder, change to the bin folder. You should see several files with .pl file extensions. Now copy the .exe files from the FrogTemp window to the c:\home\bin folder.

Now change to the C:\home folder and then to WindowsOnly\InstallTests. It should look like the bottom InstallTests screenshot. But don't click on anything. Yet.

Installing ActiveState Perl

Get ActiveStatePerl from here. Click the Download Now button. You undoubtedly want the "Free Community Edition." Choose the version that is most appropriate for your machine. (64 bit, etc.) Download it and double click on the file you downloaded. It is a standard Windows setup program so you can mostly click through the defaults. The only one to watch out for is to make sure that it adds Perl to your path.

After it is installed, switch to your InstallTests folder and click on IsPerlHere.bat You should see something like

Tests to see if Perl is installed at all.
...
This is perl 5, version 14, subversion 2 (v5.14.2) built for MSWin32-x64-multi-thread
(with 1 registered patch, see perl -V for more detail)

Copyright 1987-2011, Larry Wall

Binary build 1402 [295342] provided by ActiveState http://www.ActiveState.com
Built Oct  7 2011 15:19:36
    Press any key to continue . . .

(My Perl is several years old.) If you see something like

'perl' is not recognized as an internal or external command,
operable program or batch file.
Press any key to continue . . .

This means that Perl isn't installed. Try uninstalling it and reinstalling it and make sure to watch out for questions about putting Perl on the path. It really needs to be on the path.

Installing ImageMagick

MarkdownWrapper.pl uses the ImageMagick convert program to resize images. Download ImageMagick from here and follow the instructions. switch to your InstallTests folder and click on IsImageMagickHere.bat You should see something like

Tests to see if ImageMagick is installed at all.
...
Version: ImageMagick 6.7.7-2 2012-05-25 Q16 http://www.imagemagick.org
Copyright: Copyright (C) 1999-2012 ImageMagick Studio LLC
Features: OpenMP

Press any key to continue . . .

If so, then this is all you need. If not...try Uninstalling and reinstalling and looking out for any questions about putting ImageMagick on the path.

Adding `C:\home\bin` to your path

Editing the PATH Environment Variable
Editing the PATH Environment Variable

This can be a detour if you have never done this. To be on the safe side, let's make a backup copy of your environment variables. Switch to the InstallTests folder and click on GetEnvironmentVariables.bat It will open two windows. A DOS windows that says

C:\home\WindowsOnly\InstallTests>echo off
Displaying them in Notepad.
You need to close Notepad to exit this.

And Notepad with a copy of your environment variables. Save As them with a filename like OriginalEnvironmentVariables.txt But otherwise keep Notepad open while you do the next steps.

Editing your environment variables (Windows 7) From Windows Control Panel, click "System and Security", "System", and then "Advanced system settings" (May need administrative privileges?) The "System Properties" dialog should open up. Click on the "Advanced" tab, if needed. Then click on the Environment Variables button.

You want the bottom "System variables" window. Scroll down so the "Path" variable is highlighted. Then click on Edit....

When the "Edit..." dialog first opens, the entire path is highlighted. Danger! While it is highlighted, typing any character will overwrite the entire path. If this happens, click on Cancel immediatly.

Editing the PATH Environment Variable
Editing the PATH Environment Variable

The safer method is to press your right-arrow key to 1., de-select the selection and 2., move the curser to the end of the path. At this point you type a semicolon (';'), followed by the directory you want to add to the path. In the example shown, the end of the existing path is

C:\Program Files (x86)\GPSBabel

If you wanted to add C:\home\bin to the end of the path, you would type ;C:\home\bin right after GPSBabel Like

C:\Program Files (x86)\GPSBabel;C:\home\bin

Move around the edit box with your left and right arrows and verify that the change you made is what you wanted it to be. Examine the PATH variable in the servars.txt file to make sure that what you have edited corresponds to what the PATH variable contents are.

When you are sure you have it correct, click on OK And OK again to get out of the "Environment variables" box. OK again to get out of the "System Properties" box.

Creating the `PERL5LIB` environment variable

Creating the PERL5LIB Environment Variable
Creating the PERL5LIB Environment Variable

This is similar to "Adding a directory to your path." Same thing, except for when you get to the "System variables" window, click on the New... button.

Enter PERL5LIB for "Variable name:". Enter the path to where you put the perl5lib files. The default is
C:\home\bin\perl5lib

Then OK your way out.

Checking Switch to the InstallTests folder and click on DisplayEnvironmentVariables.bat This will display your Environment variables in a DOS window using more. Press the space bar to advance by screenfulls. Check to see if

FHOME=C:\home
PERL5LIB=C:\home\bin\perl5lib

are there. And that C:\home\bin is at the end of the PATH variable.

Editing the site specfic configuration files

Almost done. Go to the etc directory. You will see three directories: markcms is where the configuration files go. markcms-linux and markcms-windows contain files that are specfic to each platform. You, of course, want markcms-windows. So change to markcms-windows. Open frog-site-locations.cfg. The variables of interest are

# Locations that don't change (are the same for normal, mobile, and tablet sites.)

# Can be used in a navbar
# Windows (not using a web server)
_MobileSite = file:///C:/home/frog/frog_mobile/index.html
_TabletSite = file:///C:/home/frog/frog_tablet/index.html
_FullSite = file:///C:/home/frog/frog_html/index.html

These variables are used in places like navigation bars. To have links that go to the three variations. The above example is set up assuming that you aren't using any kind of server to develop on. You will be just double clicking on the .html files in Explorer and they will open in your browser. If you are using a server, then use the appropriate URLs (not file locations.)

You probably don't need to change this, so just copy it to the markcms directory. Now open frog-site.cfg, frog-mobile.cfg, and frog-tablet.cfg The important variables are like:

BaseInDir = C:\home\frog_authoring
BaseOutDir = C:\home\frog_html

BaseInDir is where the .md files are that you edit. BaseOutDir is where the html files are to be written. BaseInDir should be the same in all three files. BaseOutDir, of course, should be different--one each for "normal", "mobile", and "tablet". Again, these probably don't need to be changed--just copy them to the markcms directory. They are all included in the full configuration files that are in markcms

The reason why these site specfic configuration files weren't in markcms in the first place is so that they won't be overwritten when you load a new version of Frogdown. The only way that the site-specfic configuration files get into markcms is when you copy them yourself.

More validity checks.

In an Explorer windows change to C:\home\WindowsOnly\InstallTests Double click on TestPerl.bat, which will do a several sanity checks. If all goes well you will see

TestPerl.pl
Tests to see if you are set up to process Frogscript with MarkdownWrapper.pl

This is good:
  Module 'FrogUtils::utility' is loaded.
  Module 'FrogUtils::MarkdownW.pm' is loaded.
  Module 'FrogUtils::SmartyPantsW' is loaded.
  Module 'File::Path' is loaded.
  Module 'Digest::MD5' is loaded.
  Module 'Date::Calc' is loaded.

  Your FHOME directory is 'C:/Home/'
  Your configuration directory (C:/Home/etc/markcms/) exists.
  'frog.cfg' exists in your configuration directory

Trying unxutils program 'ls --version'. It returned
Result: 'ls (GNU fileutils) 3.16'

Which is good.
Press any key to continue . . .

If so, then good. If it complained about anything recheck the above steps. If TestPerl.bat completed OK you can go on to the next step.

ShortDemo Double click on ShortDemo.bat. A DOS windows will display

C:\home\WindowsOnly\InstallTests>echo off
Demonstration of the Frogscript system
Notepad has loaded 'ShortDemoOutput.txt'
You must close Notepad to end this.

Notepad is displaying the output of ShortDemo.pl (that is in c:\home\bin) It will explain what it did. At this point, you are good to go, so make it easy to use by doing a few more things to make it real GUI.