Installing Frogdown

Frogdown install instructions

Download and unzip Frogdown.zip. Frogdown/bin contains executable files (well, Perl scripts) that need to be to be somewhere on your path. Windows users, if you don't already have Perl installed, read Setting up a Windows machine for Frogdown.

Adding the Frogdown /bin directory to your path

Linux: All examples assume that you have created a frog user and the frog user's home directory is /home/frog (Mac: /users/frog) The shorthand for your home directory is the tilde ('~') character. For the purposes of this text, '~' and /home/frog (/users/frog) mean the same thing. If frog is your user. If you are using a different user/home directory, then adjust these instructions accordingly. If you copied the contents of Frogdown/bin (where you unzipped Frogdown.zip) to (a possibly newly created) bin directory in your home directory, you would add

export PATH=$PATH:$HOME/bin

to 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 ~/bin directory is now on the path. (If you are the frog user) you would see :/home/frog/bin at the end of your PATH variable.

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

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/bin/perllib

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 | more 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:\frog\bin\Perl5Lib
PHPRC=C:\Program Files (x86)\PHP\

Linux:

PATH=/usr/kerberos/sbin:/usr/kerberos/bin:/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin
:/usr/bin:/home/frog/bin
PERL5LIB=/home/frog/bin/perllib
PIPESTATUS=([0]="0")

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\frog

Frogdown/etc/markcms contains configuration files. (Linux: /etc/markcms needs to be wherever your HOME variable points to (set...). Windows: you need first copy the contents of Frogdown/etc/markcms to where you will be working on these. Let's say C:\home\etc\markcms Then go into Control Panel 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

Create a new directory somewhere. 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 set | more and examine the PATH variable 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
Tests to see if you are set up to process Frogdown 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.

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.

Then you need to install these real Perl modules. (Windows: use ActiveState ppm) (Linux: use whatever installer came with your distribution. yum install Digest-MD5, or suchlike. Linux guys are supposed to know these things. :-) )

Another test (Shortdemo)

(Windows: run ShortDemo.bat) (Linux: run ShortDemo.pl > ShortDemoOutput.txt and then less ShortDemoOutput.txt.) You should see something like:

Tests to see if your Perl has all the stuff that is needed to run MarkdownWrapper.pl

Here is some text formatted as Markdown:

[Lorem ipsum dolor](http://lipsum.com/) sit amet, *consectetur adipiscing
elit*. Aliquam semper condimentum urna vitae consequat. Nulla facilisi. Nam
mattis mi ut pellentesque eleifend. Proin mollis metus molestie risus
**rhoncus laoreet**.

Proin in lobortis orci, `sed auctor dogfood sapien`. Curabitur luctus velit
nec eros condimentum euismod ac quis nisl. Proin nec quam eu nisi
pulvinardapibus quis eget elit.

Here it is after running hard word wrapping
  [Lorem ipsum dolor](http://lipsum.com/) sit amet *consectetur...

 Here it is after running through Markdown()
<p><a href="http://lipsum.com/">Lorem ipsum dolor</a> sit amet, <em>consectetur...

Writing the HTML as 'lorem.html'
Writing the wordwrapped text as 'lorem-wrapped.txt'
Writing the unwrapped text as 'lorem-unwrapped.txt'

(Ellipses (...) denote text snipped for brevity.) 'ShortDemo.pl' starts with some text that is marked up using Markdown syntax. Then it uses the wrap() function from Text::Wrap to hard word wrap the text. Then uses the Markdown() function from FrogUtils::MarkdownW to convert to HTML. lorem-wrapped.txt look like

Lorem ipsum dolor

[Lorem ipsum dolor](http://lipsum.com/) sit amet, *consectetur adipiscing
elit*. Aliquam semper condimentum urna vitae consequat. Nulla facilisi. Nam
mattis mi ut pellentesque eleifend. Proin mollis metus molestie risus
**rhoncus laoreet**.

Proin in lobortis orci, `sed auctor dogfood sapien`. Curabitur luctus velit
nec eros condimentum euismod ac quis nisl. Proin nec quam eu nisi
pulvinardapibus quis eget elit.

If you load lorem.html into your browser, it should display as

Lorem ipsum dolor

(Note: Markdown handled all the escaping for lorem-wrapped.txt so the Markdown tags are displayed, rather than being interpreted as Markdown. All I had to do was indent the lines one tab stop so that Markdown treated it as a code block. And Markdown also handled rendering lorem.html--all I had to do was copy lorem.html and Markdown recognized the HTML tags and left them alone.)

Edit the config files

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

# File locations.

# Used in the navbar at the bottom of the screen
# Windows (not using a web server)
_MobileSite = ../frog_mobile/index.html
_FullSite = ../frog_html/index.html
# Linux (Using a server)
#_MobileSite = http://121.0.0.1/~frogmobile
#_FullSite = http://121.0.0.1/~frog

# BaseInDir:  Where the .md files that you are editing are located
# BaseOutDir: Where the HTML files are written to

# Windows
BaseInDir = C:\home\frog_authoring
BaseOutDir = C:\home\frog\frog_html
# Linux
#BaseInDir = ~/frog_authoring
#BaseOutDir = ~/html/frog_html

Also edit frog-mobile-site.cfg so it is exactly the same except for the BaseOutDir directory. Change that to something like

BaseOutDir = C:\home\frog\frog_mobile_html

so that the HTML for the mobile site will be written to the correct directory. All the file locations and URLs that are specfic to your site (or authoring machine) are located in these two files. MarkdownWrapper.pl reads files from BaseInDir and writes files to BaseOutDir. Get it right now and you can forget about it.

Now open frog.cfg and frog-mobile.cfg and add

### Start of Variables ###

# Print the values of config variables and then stop.
# Probably only need this when first setting up. 
# So you can make real sure that 'BaseInDir' and 'BaseOutDir'
# point to where they should before you let MarkdownWrapper.pl do any writing.
OnlyPrintConfigs = 1
# Write debugging info to the output file as HTML comments. (Use 'View Source' to see.)
Debug = 1
ShowVars = 1

You want OnlyPrintConfigs = 1 for your first run because, well, read the comments, above.

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.) Type

MarkdownWrapper.pl index.md frog

You should see (Windows):

MarkdownWrapper 1.13  2013-06-24
Read config file D:/home/etc/markcms/frog.cfg
Read config file D:/home/etc/markcms/frog-site.cfg
(Windows)

arg:             'C:/home/frog_authoring/index.md'

Basename:          'index'
Ext:               'md'
Filename:          'index.md'
htmlfile           'index.html'
Tempfile           'index.tmp'
Config             'frog.cfg'

Path:              'C:/home/frog/authoring/'
HomePath:          'C:/home/'
ConfigPath         'C:/home/etc/markcms/'
real pwd:          'C:/home/frog_authoring/'
JustDir:           ''
BaseInDir:         'C:/home/frog_authoring/'
BaseOutDir:        'C:/home/frog/frog_html/'
OutDir:            'C:/home/frog/frog_html/'

where

BaseInDir:         'C:/home/frog_authoring/'
BaseOutDir:        'C:/home/frog/frog_html/'
OutDir:            'C:/home/frog/frog_html/'

are the ones you need to check. Because this is where MarkdownWrapper reads and writes files. If BaseInDir and BaseOutDir are correct, then change OnlyPrintConfigs = 1 to be OnlyPrintConfigs = 0 in frog.cfg. Now you can type

MarkdownWrapper.pl index.md frog

and you should see (Windows:)

MarkdownWrapper 1.13  2013-06-24
Read config file C:/home/etc/markcms/frog.cfg
Read config file C:/home/etc/markcms/frog-site.cfg
Worklog:
cp -fp "C:/home/frog/authoring/frog.css" "C:/home/frog/frog_html/frog.css"
Created HTML file: C:/home/frog/frog_html/index.html

(Linux:)

MarkdownWrapper 1.13  2013-06-24
Read config file /home/frog/etc/markcms/frog.cfg
Read config file /home/frog/etc/markcms/frog-site.cfg
Worklog:
cp -fp "/home/frog/frog_authoring/frog.css" "/home/frog/html/frog_html/frog.css" 
Created HTML file: /home/frog/html/frog_html/index.html

(Apache DocumentRoot points to /home/frog/html/frog_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 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 frog-mobile frog-tablet (the names of your configuration files.)

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 for all three (in this case) 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:

echo off
Rem Windows batch file to run MarkdownWrapper.pl
Rem (Perl says that we are 'MSWin32'
Rem Running MarkdownWrapper.pl

MarkdownWrapper.pl "DogFood.md" "frog"
MarkdownWrapper.pl "DogFood.md" "frog-mobile"
MarkdownWrapper.pl "DogFood.md" "frog-tablet"
MarkdownWrapper.pl "FrogdownInstall.md" "frog"
MarkdownWrapper.pl "FrogdownInstall.md" "frog-mobile"
MarkdownWrapper.pl "FrogdownInstall.md" "frog-tablet"
MarkdownWrapper.pl "FrogdownWindows.md" "frog"
MarkdownWrapper.pl "FrogdownWindows.md" "frog-mobile"
MarkdownWrapper.pl "FrogdownWindows.md" "frog-tablet"

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

#!/bin/bash
#
# Generated by DoAllFrogs.pl 1.01 2013-06-30
# (Perl says that we are 'linux'
# Running MarkdownWrapper.pl

MarkdownWrapper.pl "DogFood.md" "frog"
MarkdownWrapper.pl "DogFood.md" "frog-mobile"
MarkdownWrapper.pl "DogFood.md" "frog-tablet"
MarkdownWrapper.pl "FrogdownInstall.md" "frog"
MarkdownWrapper.pl "FrogdownInstall.md" "frog-mobile"
MarkdownWrapper.pl "FrogdownInstall.md" "frog-tablet"
MarkdownWrapper.pl "FrogdownMac.md" "frog"
MarkdownWrapper.pl "FrogdownMac.md" "frog-mobile"
MarkdownWrapper.pl "FrogdownMac.md" "frog-tablet"
MarkdownWrapper.pl "FrogdownWindows.md" "frog"
MarkdownWrapper.pl "FrogdownWindows.md" "frog-mobile"
MarkdownWrapper.pl "FrogdownWindows.md" "frog-tablet"

Technical Tidbit

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

Loose ends (Mobile and Tablet site)

The mobile and tablet sites use jQuery Mobile. The mobile site(s) needs the "themes" directory that is in the authoring directory. MarkdownWrapper.pl can only copy single files (works for .css files), so it is up to you to copy the themes directory to the html directory where the mobile version of the site is. Sorry. I'll fix this eventually. A properly configured MarkdownWrapper.pl should copy/generate everything else.

Except...if you use native Markdown syntax for images, then you have to manually copy the image files from your authoring/images directory to the HTML/images directories. MarkdownWrapper.pl will resize and copy images if you use the Frogdown %imagebox... markup.

(To be continued.)