Setting up a Windows machine

Short version

2022-04-12

• Create C:\home
• Download Frogdown.zip and unzip it in C:\home It will unzip into C:\home\Frogdown
• Download and install Strawberry Perl You may need to install Perl modules
• Download and install ImageMagick Make sure that convert.exe is on the path (magick.exe for newer versions of ImageMagick.)
• Add C:\home\Frogdown\bin (Frogdown scripts) and
  C:\home\Frogdown\WindowsOnly\bin (UnxUtils programs) to the path .
• Add FHOME=C:\home and PERL5LIB=C:\home\Frogdown\bin\perl5lib environment variables.
• Copy site specfic files from C:\home\Frogdown\etc\markcms-windows to C:\home\Frogdown\etc\markcms Maybe look at them.
• Navigate to C:\home\Frogdown\WindowsOnly\bin and run (in this order)
  AreunxutilsProgramsHere.bat
DisplayEnvironmentVariables.bat
IsImageMagickHere.bat
IsPerlHere.bat
TestPerl.pl (And checks that required Perl modules are installed.)
  Check that none of them complain. If so, then fix any problems that are reported. Maybe skim the rest of the page.
• Optional. Install a web server, such as Apache2
• Look over the Intro to Frogdown

Long version

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

Getting the files

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.

Download Frogdown.zip (2022-04-28 02:41 PM 3.3 MB) into C:\home and unzip it. It should unzip to C:\home\Frogdown

FrogdownScripts.zip (2022-04-28 02:41 PM 616.6 KB) is just the scripts and supporting files without all the Frogdown .md files and image files, in case you already have all the rest and just want the latest version of the Frogdown scripts.

Installing Perl

2022-04-13 I switched to Strawberry Perl.

To install CPAN modules in Strawberry Perl

c:
cd \Strawberry\perl\bin
cpan File::Path
cpan Digest::MD5
cpan Date::Calc

(Don't install CPAN modules until TestPerl.pl complains that they are missing! Wait until we get to the "More validity checks" section.) Installing CPAN modules will take a while with lots of stuff scrolling on the screen. Go get a cup of coffee while the CPAN module installation is happening.

Or you can use ActiveStatePerl from here. I used to use ActiveState Perl until I was updating the Frogdown documentation and installing Frogdown on my laptop. I was befuddled when I tried to install CPAN modules into ActiveState Perl. I uninstalled ActiveState Perl and installed Strawberry Perl and was able to install CPAN modules into Strawberry Perl. YMMV.

Installing ImageMagick

MarkdownWrapper.pl uses ImageMagick to resize images. Download ImageMagick from here and follow the instructions. switch to your C:\home\Frogdown\WindowsOnly\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 ImageMagick is installed and is on the path. If not...try Uninstalling and reinstalling and looking out for any questions about putting ImageMagick on the path.

You need some UnxUtils programs

You need some of the programs from UnxUtils, which is a collection of common UNIX (and Linux) command line programs. MarkdownWrapper.pl uses some of these and assumes that they exist and are on your path. Frogdown.zip includes the UnxUtils programs we need, in the
C:\home\Frogdown\WindowsOnly\bin directory. The next section tells how to add this to your path (so you don't need to download then entire UnxUtils suite).

If you want the entire UnxUtils suite of programs, download and unzip UnxUtils.zip, copy the individual programs to a convenient directory and then add this directory to your path.

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

2022-04-13 These docs were originaly written for Windows 7. The dialog boxes for later versions of Windows are different but the objective is the same: to edit the environment variables.

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 C:\home\Frogdown\WindowsOnly\InstallTests folder and click on GetEnvironmentVariables.bat It will open two windows. A DOS windows that says

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.

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\Frogdown\bin to the end of the path, you would type ;C:\home\Frogdown\bin right after GPSBabel Like

C:\Program Files (x86)\GPSBabel;C:\home\Frogdown\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.

Also add the UnxUtils directory (that comes with Frogdown)
C:\home\Frogdown\WindowsOnly\bin to the path.

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\Frogdown\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\Frogdown\bin\perl5lib

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

Editing the configuration files

Almost done. Go to the etc directory. You will see four directories: markcms is where the configuration files go. markcms-linux, markcms-linux-raspberry-pi and markcms-windows contain files that are specfic to each platform. You, of course, want markcms-windows. So change to markcms-windows. Copy the contents of markcms-windows to markcms. Change to C:\home\Frogdown\etc\markcms.

Open frog-site.cfg and look at

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

BaseInDir is where the .md files are that you edit. BaseOutDir is where the html files are to be written. ` Again, these probably don't need to be changed

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 (by downloading and unzipping Frogdown.zip.) The only way that the site-specfic configuration files get into markcms is when you copy them yourself. Frogdown.zip is for both Windows and Linux and having different versions of the configuration files keeps us all sane.

More validity checks.

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

TestPerl.pl  1.02  2022-04-11
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/Frogdown/'
  Your configuration directory (C:/home/Frogdown/etc/markcms/) exists.
  'frog.cfg' exists in your configuration directory.
  'frog-site.cfg' exists in your configuration directory.

Testing for several unxutil programs we need...
Good.  3 out of 3 unxutils programs were found.

Testing to see if ImageMagick is installed
Good! ImageMagick (magick) is installed

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.

Drag-and-drop to process .md files

There are two batch files in the Frogdown directory that are designed to process .md files with drag-and-drop:

DragOntoDebug.bat For debugging. It will process the .md file with the debug option (that shows a lot of configuration variables but doesn't generate any .html files.)

DragOntoDoOne.bat For normal processing. When you ae done editing a .md file and have saved it, drag the .md file onto DragOntoDoOne.bat. For example, to process index.md to create index.html:

You should see

Drag-and-drop an .md file onto this.
Runs MarkdownWrapper.pl on C:\home\Frogdown\frog_authoring\Frogdown\index.md (no debug)

MarkdownWrapper 0.45  2022-04-11
Read config file C:/home/Frogdown/etc/markcms/frog.cfg
Read config file C:/home/Frogdown/etc/markcms/frog-site.cfg
Read config file C:/home/Frogdown/etc/markcms/frog-site-locations.cfg
Read input file: 'index.md'
Testing to see if ImageMagick is installed
Good! ImageMagick (magick) is installed
Substitutions = 'D\:\/home|c:/home' 'D\:\/home' will be replaced by 'c:/home'
Worklog:
Converted CSS template vars and wrote 'C:/home/Frogdown/frog_html/Frogdown/frog.css'
Created text file: C:/home/Frogdown/frog_html/Frogdown/index.text
Included file 'Frogymanheader.inc'
Created text file: C:/home/Frogdown/frog_html/Frogdown/Frogymanheader.inc
Created HTML file: C:/home/Frogdown/frog_html/Frogdown/index.html

Navigate to C:/home/Frogdown/frog_html/Frogdown/index.html and double click on index.html It should open in your browser. If it does, then cool. Now go back to C:\home\Frogdown\frog_authoring\Frogdown and double click on DoAllFrogs.bat This will generate GenAll.bat.

echo off
Rem Windows batch file to run MarkdownWrapper.pl
Rem (Perl says that we are 'MSWin32'
Rem Generated by DoAllFrogs.pl 1.02 2013-07-09
Rem Running MarkdownWrapper.pl

MarkdownWrapper.pl "copy-sd-cards.md" "frog"
MarkdownWrapper.pl "DogFood.md" "frog"
MarkdownWrapper.pl "FrogdownInstall.md" "frog"
MarkdownWrapper.pl "FrogdownWindows.md" "frog"
MarkdownWrapper.pl "FrogPi.md" "frog"
MarkdownWrapper.pl "FrogPiShort.md" "frog"
MarkdownWrapper.pl "FrogSteps.md" "frog"
MarkdownWrapper.pl "index.md" "frog"
MarkdownWrapper.pl "MakingItGUI.md" "frog"
MarkdownWrapper.pl "PiRef.md" "frog"
pause

Double click on GenAll.bat It will create all the rest of the Frogdown .html files.

Write using the copy-paste method.

Study the .md files for a while. Then start creating your own files by copying-and-pasting relevant portions from the existing .md file (usually the header stuff at the beginning of .md file.) For tricky things like sidebars and imageboxes, copy-and-paste examples from existing .md files that do what you want. Change as needed. (I still use this method.)

Skim through Introduction to Frogdown.

Use Notepad++ to edit

I use Notepad++ to edit Perl and .md files. It is handy for writing Perl because it color codes Perl syntax. It also inserts itself on the right-click menu you get when you right-click a file. So you can right-click a .md file (or any other type of file) and open it with Notepad++. This is a termendous advantage because it makes Perl programs have a (sort of) GUI interface.