Installing Frogdown

Frogdown install instructions

(This page last modified on 2022-04-27 12:56 PM)

Important note!

April 12, 2022 I've changed some of the paths since this document was first written in 2013. In general, the Frogdown distribution assumes that you are in your home directory (~ for Linux, and (maybe) C:\home for Windows. Put the Frogdown.zip file in your home directory and unzip it there. It will unzip to a Frogdown directory. So you will end up with (for instance) ~/Frogdown/frog_authoring, etc. (Linux), C:\home\Frogdown\frog_authoring, etc. (Windows) I updated this page but haven't updated the other Windows related pages yet.

If you want to install Frogdown on a commercially hosted web server (like GoDaddy), then it is really best to first install it on a local machine (i.e., your own Windows machine or a Raspberry Pi that you own. Poke it and prod it. After you understand how it all works, then upload Frogdown.zip to the hosted site, unzip it in a temporary directory, and then move the various Frogdown subdirectories to someplace that is compatible with the hosted site. I just got done doing this with my own GoDaddy Frogymandias site after GoDaddy "upgraded" to CPanel and all the Frogdown related programs disapeared and I had to install them from scratch. I referred to the Frogdown documentation to do this. Which triggered "um, the documentaton is really out of date..."

Download and unzip Frogdown.zip (2022-04-28 02:41 PM 3.3 MB). Frogdown/bin contains executable files (well, Perl scripts) that need to be to be somewhere on your path.

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

Windows users, if you don't already have Perl installed, read Setting up a Windows machine for Frogdown (Mostly)

Or by Installing Frogdown on a Raspberry P. (Newest documentation. Especially for Linux users.)

Add the Frogdown /bin directory to your path

Linux: The shorthand for your home directory is the tilde ('~') character. If you unzipped Frogdown.zip in your ~ (home) directory, you should add ~/Frogdown/bin to your path. $HOME is the same thing as ~. Hence, add

export PATH=$PATH:$HOME/Frogdown/bin

to the end of your .bashrc file. And then log out and in again. If you look at your PATH environment variable (echo $PATH), you should see that the ~/Frogdown/bin directory is now on the path.

Important note!

The Linux instructions assume that you are administering your own server. If you are on a hosted server (like a basic GoDaddy account) you need to check the rules. Adapt these instructions accordingly. (I just reworked Frogdown to work on GoDaddy after the hosting was "upgraded" to cPanel, which broke changed a lot of things.)

For example, GoDaddy has already set the PERL5LIB environment variable so you shouldn't change it. TestPerl.pl (below) will show you the PERL5LIB locations (if it can't find the necessary Perl modules.) Put your .pm files in one of these directories.

Linux: You can add

# Add Frogdown /bin directory to path
PATH=$PATH:$HOME/bin:$HOME/Frogdown/bin
export PATH

to the end of .bashrc (or .bash_profile). (~/Frogdown/bin is where the Frogdown scripts ended up.)

Windows: sort of the same idea, but see Setting up a Windows machine for Frogdown Specifically, How to add a directory to your path on Windows.. (Are you seeing a pattern here?) Also, the '~' convention is only for Linux (or Macs)

Windows: You need to have some of the UnxUtil utility programs on your path. The UnxUtils programs we need are in
C:\home\Frogdown\WindowsOnly\bin You can add this directory to your path without needing to download the complete UnxUtils.

Setting the 'PERL5LIB' environment variable

Note that Frogdown/bin contains Frogdown/bin/perl5lib The contents of the perl5lib directory are the Perl module files. You need to set your PERL5LIB environment variable to point to wherever your perl5lib directory ends up. I find it convenient to leave it on top of my regular local bin directory. (The perl5lib directory does not need to be on your path.) Linux, assuming that you copied the perl5lib files to your ~/bin/perl5lib dirctory, you would add

# Set environment variable so that Perl can find the library files
export PERL5LIB=$HOME/Frogdown/bin/perl5lib

to your .bashrc file and then log off and on again. (Windows: See Setting up a Windows machine for Frogdown, if needed.) Create a new MS-DOS command prompt window) Then type set | less to display all your environment variables so you can verify that your PERL5LIB variable is set correctly.

Windows:

PATHEXT=.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC
PERL5LIB=C:\frogdown\bin\Perl5Lib
PHPRC=C:\Program Files (x86)\PHP\

Frogdown/ contains files that should go on your HOME directory. A home directory structure is a Linux (well, UNIX) convention. I use the same convention on my Windows machine. I created a C:\home directory for all my web projects. For this project, everything lives in C:\home\frogdown (My machine has the entire Frogymandias site so it is set up slightly different than how I am describing for just Frogdown.)

Frogdown/etc/markcms contains configuration files. (Win 10) go into Control Panel\System and Security\System, scroll down to Advanced settings and then click Environment variables and create a new environment variable for FHOME with the value of C:\home Now MarkdownWrapper.pl will be able to find the configuration files.

Testing your Perl installation

From a command prompt, type TestPerl.pl. If you get 

'TestPerl.pl' is not recognized as an internal or external command,
operable program or batch file.

(Windows) or 

-bash: TestPerl.pl: command not found

(Linux) then your Frogdown Perl scripts aren't on your path. Type echo $PATH to see if the bin directory you created is somewhere on the path. (Windows: you can use Explorer and double click on TestPerl.bat.)

If TestPerl.pl ran it should display something like

TestPerl.pl  1.02  2022-04-11
Tests to see if you are set up to process Frogscript with MarkdownWrapper.pl
'FHOME' is used in place of 'HOME'

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 HOME directory is '/home/pi/Frogdown/'
  Your configuration directory (/home/pi/Frogdown/etc/markcms/) exists.
  'frog.cfg' exists in your configuration directory.
  'frog-site.cfg' exists in your configuration directory.

Testing to see if ImageMagick is installed
Good! ImageMagick (convert) is installed. Which is close enough.

If you see something like

This is good:
  Module 'File::Path' is loaded.
  Module 'Digest::MD5' is loaded.

This is not good:
  Uh, oh.  Module 'FrogUtils::utility' does not seem to be installed.
  Uh, oh.  Module 'FrogUtils::MarkdownW.pm' does not seem to be installed.
  Uh, oh.  Module 'FrogUtils::SmartyPantsW' does not seem to be installed.

then Perl can't find the Frogdown support scripts. Reread the PERL5LIB section, above. If you see

This is good:
  Module 'FrogUtils::utility' is loaded.
  Module 'FrogUtils::MarkdownW.pm' is loaded.
  Module 'FrogUtils::SmartyPantsW' is loaded.

This is not good:
  Uh, oh.  Module 'File::Path' does not seem to be installed.
  Uh, oh.  Module 'Digest::MD5' does not seem to be installed.

Installing Perl Modules

Then you need to install these real Perl modules. (Windows: use ActiveState ppm Maybe. ActiveState Perl is different now.)

Windows Strawberry Perl:

c:
cd \Strawberry\perl\bin
cpan Digest::MD5

Linux: use whatever installer came with your distribution. yum install Digest-MD5 (Red Hattish). Raspberry Pi and Debian

Edit the config files

No more separate mobile site

3/27/2022 Frogdown and the documentation was written when people used separate mobile sites. We don't do this anymore so you can probably ignore anything having to do with mobile sites.

Use responsive web design instead. (It involves tricky .css files.) The Frogmandias site now uses responsive design.

Go to where you put etc/markcms and load frog-site.cfg into a text editor. It should look like

Windows:

# File locations for regular site.

Include = frog-site-locations.cfg

# Windows
# BaseInDir are where we read the .md source files from
BaseInDir = C:\home\Frogdown\frog_authoring

# BaseOutDir: Where the HTML files are written to
BaseOutDir = C:\home\Frogdown\frog_html

Linux (and Raspberry Pi):

# File locations for regular site.

Include = frog-site-locations.cfg

# BaseInDir: Where the Frogdown .md markup files are
# BaseOutDir: Where the HTML files are written to

# Linux (You might need to change these, depending on how
# your distro (or hosting service) is set up
# .md files you edit are here
BaseInDir = ~/Frogdown/frog_authoring

# The converted .html files will be written here
# Assuming that you changed Apache2's DocumentRoot.
# Or haven't installed any web server.
BaseOutDir = ~/Frogdown/frog_html
# Apache2 default (which may be owned by root.  chown -R...)
#BaseOutDir = /var/www/html

Generating your web site

You can do this one file at a time. As you are editing the files. Open another command prompt window and change your authoring directory that has all the .md files. (Windows users: if you are following the Setting up a Windows machine for Frogdown instructions, you don't need to use the command prompt at all.) Drag index.md onto DragOntoDebug.bat

You should see (Windows):

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

Basename:          'index'
Ext:               'md'
Filename:          'index.md'
htmlfile           'index.html'
ImageMagick is:    'magick'
Config             'frog.cfg'

CurrentDrive:      'C:'
HomePath:          'C:/home/Frogdown/'
ConfigPath         'C:/home/Frogdown/etc/markcms/'
Path (pwd):        'C:/home/Frogdown/frog_authoring/Frogdown/'
real pwd:          'C:/home/Frogdown/frog_authoring/Frogdown/'
JustDir:           'Frogdown/'
%%PathToHome%%:    '../'
BaseInDir:         'C:/home/Frogdown/frog_authoring/'
BaseOutDir:        'C:/home/Frogdown/frog_html/'
InDir:             'C:/home/Frogdown/frog_authoring/Frogdown/
OutDir:            'C:/home/Frogdown/frog_html/Frogdown/
FilestoBeCopied:   'frog.csst
'

(Windows)
Debug mode--did not create any files.

where

BaseInDir:         'C:/home/Frogdown/frog_authoring/'
BaseOutDir:        'C:/home/Frogdown/frog_html/'
InDir:             'C:/home/Frogdown/frog_authoring/Frogdown/
OutDir:            'C:/home/Frogdown/frog_html/Frogdown/

are the ones you need to check. Because this is where MarkdownWrapper reads and writes files. If BaseInDir and BaseOutDir are correct you should be good to go.

Linux: 

MarkdownWrapper 0.45  2022-04-11
Read config file /home/pi/Frogdown/etc/markcms/frog.cfg
Read config file /home/pi/Frogdown/etc/markcms/frog-site.cfg
Read config file /home/pi/Frogdown/etc/markcms/frog-site-locations.cfg
Changing '~' to '/home/pi/' in '~/Frogdown/frog_authoring'
  is now '/home/pi/Frogdown/frog_authoring'
Read input file: 'index.md'
Testing to see if ImageMagick is installed
Good! ImageMagick (convert) is installed

Basename:          'index'
Ext:               'md'
Filename:          'index.md'
htmlfile           'index.html'
ImageMagick is:    'convert'
Config             'frog.cfg'

HomePath:          '/home/pi/'
ConfigPath         '/home/pi/Frogdown/etc/markcms/'
Path (pwd):        '/home/pi/Frogdown/frog_authoring/Frogdown/'
real pwd:          '/home/pi/Frogdown/frog_authoring/Frogdown/'
JustDir:           'Frogdown/'
%%PathToHome%%:    '../'
BaseInDir:         '/home/pi/Frogdown/frog_authoring/'
BaseOutDir:        '/var/www/html/'
InDir:             '/home/pi/Frogdown/frog_authoring/Frogdown/
OutDir:            '/var/www/html/Frogdown/
FilestoBeCopied:   'frog.csst
'

(Linux)
Debug mode--did not create any files.

where

BaseInDir:         '/home/pi/Frogdown/frog_authoring/'
BaseOutDir:        '/var/www/html/'
InDir:             '/home/pi/Frogdown/frog_authoring/Frogdown/
OutDir:            '/var/www/html/Frogdown/`

are the ones you need to check. Because this is where MarkdownWrapper reads and writes files.

/var/www/html would be if you had a web server installed and DocumentRoot was set to be /var/www/html and you had done sudo chown -R for the html tree so it is writable by you. If not, then it should be

BaseInDir:         '/home/pi/Frogdown/frog_authoring/'
BaseOutDir:        '/home/pi/Frogdown/frog_html'
InDir:             '/home/pi/Frogdown/frog_authoring/Frogdown/
OutDir:            '/home/pi/Frogdown/frog_html'

If BaseInDir and BaseOutDir are correct you should be good to go.

(Windows) Now you can drag index.md onto DragOntoDoOne.bat

and you should see (Windows:)

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
Making C:/home/Frogdown/frog_html/Frogdown/screens
mkdir C:/home/Frogdown/frog_html/Frogdown/screens
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
magick "screens\frog-logo.jpg" -resize 212.5x212.5^> -unsharp 0x0.35+1+0 -compress JPEG -quality 80 "C:\home\Frogdown\frog_html\Frogdown\screens\frog-logo.jpg"
Created HTML file: C:/home/Frogdown/frog_html/Frogdown/index.html

(Linux:)

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

(Apache DocumentRoot points to /var/www/html/)

which indicates that MarkdownWrapper.pl is working correctly.

Use 'DoAllFrogs.pl' to automate generating your web site

The /bin directory contains a DoAllFrogs.pl Perl script that generates a GenAll.bat batch (Windows) or GenAll.sh shell (Linux) script that will run MarkdownWrapper.pl on all .md files in the directory. To use it, make sure that DoAllFrogs.pl is on your path (which it should be if it is in your /bin directory) and is properly chmodded (Linux/Mac only.) Then change to your authoring directory. Type

DoAllFrogs.pl frog (the names of your configuration file.)

DoAllFrogs.pl will then generate the appropriate GenAll script for your platform. The GenAll script will run MarkdownWrapper.pl for all .md files in the directory, with all the configuration files. (So you can generate all the HTML files sites.) Examine it. Edit it. Rename it. etc. It is an aid for generating the HTML files.

Example, a GenAll.bat script (for Windows) that was created by DoAllFrogs.pl could be like:

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 "index.md" "frog"
MarkdownWrapper.pl "PiRef.md" "frog"
MarkdownWrapper.pl "SomePHP.md" "frog"
MarkdownWrapper.pl "WhatsNew.md" "frog"
pause

etc. A GenAll.sh script for Linux (or Macs) could be like:

#!/bin/bash
#
# Generated by DoAllFrogs.pl 1.03 2022-04-15
# (Perl says that we are 'linux'
# 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 "index.md" "frog"
MarkdownWrapper.pl "PiRef.md" "frog"
MarkdownWrapper.pl "SomePHP.md" "frog"
MarkdownWrapper.pl "WhatsNew.md" "frog"

Technical Tidbit

DoAllFrogs.pl tests the special Perl variable $^O to determine if it is running under Windows or Linux (Macs are the same as Linux, as far as any of these Perl scripts are concerned.) Like

if ( $^O =~ /MSWin.*/i ) {
    print "We are running under Windows\n";
} else {
    print "We are running under Linux (or are a Mac)\n";
}

Other than creating .bat or .sh files, there is surprisingly little difference between running under Windows or running under Linux (or Macs.) Take a quick look through MarkdownWrapper.pl and see there isn't much code running under a if ( $^O =~ /MSWin.*/i ) test. And the Perl scripts work the same no matter if they are used on your Windows (or Mac) desktop machines or if they are running on a web server. FWIW.

Optional: Install Apache2 (and PHP) for Linux

It is handy to have a real web server running on your machine to test against. Other devices on your subnet can access the server. For example, you can also use it to put "to do" lists on that you can see from all your devices.

This is assuming that you own the machine. Don't try this if you are using a commercially hosted web server (like GoDaddy)! Or are using anybody else's machine (without asking permission.)

Here is how to install Apache2 (and PHP)

Installing other distros of Linux (on a cheap refurb?)

Here are some notes on installing Debian 11 (BullsEye)

At this time I don't know the best way to install a web server on Windows, so I'll leave it up to Google. This is a good excuse to have a Raspberry Pi to experiment with. Or...

Get a cheap refurb PC to install Linux on

Or get a cheap refurb PC and install something like Debian. (Hint. Replace the slow spinning HD that comes with a cheap refurb with a cheap SSD) A 120 GB SSD is more than enough for this kind of testing. As is 4 gigs of RAM. An Intel Core 2 Duo with an SSD will fly running Linux. For the purposes of testing Frogdown on a Linux server.

Right now I'm using some Raspberry Pi machines I already had to test the Linux install but the supply of Raspberry Pi machines is almost non-existant at the present time. But low-end refurb PCs are still cheap and plentiful. When I checked just now, Discount Electronics had a deal to get two refurbs (without disk or operating system) for $50. Add a cheap SSD and install a distro. Debian what the Raspberry Pi OS is based on so if you use Debian, you will be mostly trained for when Raspberry Pis are back in stock at the normal retail price. (My Raspberry Pi install documentation is probably applicable to Debian.)

Loose ends (Mobile and Tablet site)

3/26/2022 Mobile and tablet sites are deprecated because nobody does sites this way anymore--we now use a single "responsive" design that (presumably) automatically changes so it works for both mobile and desktop.