### Start of Variables ### # Variables that start with "_" are template variables # If found, the leading "_" will be removed. # They are used to match "%%Variable%% template variables in # template pieces in the configuration files. # _PageTitle is used in the Page Header template. # i.e. %%PageTitle%% etc. _PageTitle = Intro to Frogdown # _PageID isn't used yet. But it will be--make sure that every page has a unique _PageID. _PageID = dogfood ### Optional variables ### # New for version 1.10 # You can use define and use %%template%% variables in your own document. # Well, if TemplateVarsInBody = 1 (below) _Language = Frogdown # or maybe #_Language = Frogdown # Force all images to be created? # (Usually only needed when you are fiddling with image sizes.) # Or if you are experimenting with ImageMagickConfig in the config files ForceImageCreation = 0 # Put assorted config variables as comments at the start of the output file. # Probably should only be used while debugging. Debug = 0 ShowVars = 1 # Also generate a word wrapped version of this file? # Only is needed if you want to make this file available on the site. MakeTextFile = 1 ### End of Variables ### %%Include Frogymanheader-1.inc%% %id dogfood nl|ht = If you are reading this you have discovered that I like hover text. So hover over things. Hover over the Froggy picture over there.% ###Eat your own dogfood %#%We can include other files%/#% %%Include DogFood-Include.inc%% %ClearFloats% > (Hover over the links for an overview.) %%NameLinks%% %id frogdown nl | ht = Frogdown is Markdown with a lot of extra features% ###What is Frogdown? First, Frogdown is a superset of [Markdown](http://daringfireball.net/projects/markdown/), which is a very popular minimal text markup language. It is very popular because you don't need to add much markup code at all, so text that is formatted in Markdown is easy to write. Look at [Markdown Basics](http://daringfireball.net/projects/markdown/basics) and [Markdown: Syntax](http://daringfireball.net/projects/markdown/syntax) to see how to format Markdown. However, Markdown is limited, so Frogdown was written to add more functionality to Markdown. For a demonstration of Frogdown syntax, look at [DogFood.text](DogFood.text) for the Frogdown markup for this page. (Might not work on the mobile version of this.) FrogDown (as implemented in MarkdownWrapper.pl) is designed to run on both Windows and Linux (and maybe Macs). Because it is a Perl script, it works on a desktop machine, or can be used on a server. FrogDown (MarkdownWrapper.pl) is template driven. It is currently configured to generate both [normal](%%FullSite%%) and [mobile](%%MobileSite%%) versions of your web pages. %id frogdowninline ht=These work within a block level structure (i.e., a paragraph or div). For things like bold or italic.% ###Frogdown inline markup tags Look at [the original markup file](DogFood.text) to see the codes. Use your browser's "View/Source" function to see the HTML code that MarkdownWrapper.pl generated. %b%This text is bold%/b% %i%This text is italic%/i% %bi%This text is bold/italic%/bi% %br%(There should have been a line break just before this because I used the `\%br%` tag.) %em%This text is emphasized%/em% %strong%This text is strong%/strong% %#%This text shouldn'be be here because it is an inline comment.%/#% %tt%This text is in the typewriter font. See how \%tt\% handles troublesome text.%/tt% This text is unadorned. %code%This text is in \%code\%. See how \%code\% handles troublesome text.%/code% %sidebar sb=bqsidebar|t=Detail% \%code\%%b%{Some Text}%/b%\%/code\% runs %b%{Some Text}%/b% through Markdown to escape special characters that HTML will interpret. \%tt\% just wraps %code%%/code% around the text, so the '%code%<>%/code%' characters aren't escaped. The previous paragraph illustrated the difference between how text that is enclosed in the Frogdown tags \%tt\% and \%code\% are handled. And note that the '%' character needs to be escaped with a ’\\’ %#%We need a bit of ugly escaping to display the \\ character with adjacent single quotes. When SmartyPants is enabled.%/#% character when writing about Frogdown code. So that \%tt\% is displayed and is not treated as the start of a \%tt\%block. Sometimes the dogfood isn't tasty as one would hope. %/sidebar% %id sidebar ht = are text boxes that are set off in some way. Like with a lined border around them and a gray background. And maybe floating to the left or right. That kind of thing.% ###Sidebars Sidebars are text boxes that are set off in some way. (The actual look and feel is defined in the CSS style sheet that is defined for the page.) Frogdown code for a sidebar would be
\%sidebar sb=bqsidebar|t=Detail\% As much Frogdown/Markdown text as you want \%/sidebar\% where `\%sidebar` starts the sidebar block, `sb=bqsidebar` defines the type of sidebar (currently has support for `bqsidebar` for block quoted, `rsidebar` for right floating and `lsidebar` for left floating.) `t=Detail` is the text for the subheading. Arguments are separated with '|' characters. %sidebar sb=bqsidebar|t=Detail% The value for `\%sidebar sb=bqsidebar%` is passed to the HTML code so you can use any value that you have in your CSS sheet. I currently have CSS styles defined for `lsidebar`, `rsidebar`, and `bqsidebar`. i.e. `sb=bqsidebar%` gets translated to
Hint: use %b%View Source%/b% in your browser. %/sidebar% %id inlineimages ht = Like HTML <img src=...> type tags but are easier to type, support floating, and have hover text.% ###Inline images Donec nec convallis ante. %img i=../images/frog-logo.png|mwp=25|f=l|t=Left floating% %img i=../images/frog-logo.png|mwp=25|f=r|t=Right floating% Donec vehicula sodales elementum. Quisque malesuada euismod est, at dignissim orci sagittis quis. Nam justo lectus, semper id magna sit amet, varius aliquet nibh. Cras ornare eros ut mi vulputate, vitae feugiat tortor congue. Proin quis lacinia metus. Suspendisse porttitor non ligula et elementum. Nulla facilisi. Nullam mi lorem, vehicula vitae ligula non, ultrices tempus ligula. Aliquam bibendum, magna eget ultrices imperdiet, est urna fermentum justo, ac facilisis purus libero nec enim. Donec porttitor magna at urna viverra, ac dapibus erat interdum. Aenean sed nibh suscipit, facilisis mauris eu, consequat lacus. Curabitur viverra tincidunt magna, sit amet semper elit tempus vel. Tagged like \%img i=../images/frog-logo.png|mwp=25|f=l|t=Left floating\% The parameters are > %table b=0 | cs=3 | cp=1 | bg=#dedede % !Tag|Description %b%i%/b%|Image name. Just like %tt%<img src="...%/tt% in HTML. (Can also be %b%img%/b%.) %b%mwp%/b%|%b%M%/b%inimum %b%W%/b%idth in %b%P%/b%ercentage. Just like how it works in the %tt%imagebox%/tt% tag, below. %b%f%/b%|Float. %b%l%/b% and %b%r%/b% for left and right (as demonstrated above.) There is also %b%c%/b% for a non-inline (block) centered image. %b%t%/b%|Title. Is the text that displays when you hover your mouse over the image. %/table% (You can also use the same parameters as `imagebox`. Except for 'caption'.) Shrug, I merged the code so they both use mostly the same code now.) %id imagebox ht = Images as block level. So they can, for example, be wrapped in a border using CSS. And have a caption. Our Froggy logo, above, is an Imagebox. Even neater, you can have an Imagebox inside of a sidebar text box.% ###Image boxes %imagebox img=../images/60D_9544.jpg|ib=bcimagebox|mwp=60|fic=0|fa=_large|c=Macro goodies|t=What good comes from stalking flowers with a macro lens? You can't eat flowers.% %imagebox img=../images/60D_9544.jpg|ib=limagebox|mwp=33|fic=0|fa=_smallish|c=Macro goodies|t=What good comes from stalking flowers with a macro lens? You can't eat flowers.% Image boxes are formatted like \%imagebox img=images/60D_9544.jpg|ib=limagebox|mwp=30|c=Macro goodies\% `images/60D_9544.jpg` is the image, `ib=rimagebox` specifies the type of image box. Currently limited to `limagebox`, `rimagebox`, and `bqimagebox` for left floating, right floating, and not-floating block quote styles. `mwp=35` is the image width, specified as a percentage. i.e., 35% (of the `MaxImageWidth` value that is defined in the configuration file.) `c=Macro goodies` is the caption. `t=...` for the "Title" (which is hover text.) %ClearFloats% > %table b=0 | cs=3 | cp=1 | bg=#dedede % !Tag|Description %b%img%/b%|Image name. Just like %tt%<img src="...%/tt% in HTML. (Can also be %b%img%/b%.) %b%mwp%/b%|%b%M%/b%inimum %b%W%/b%idth in %b%P%/b%ercentage. Explained in the previous paragraph, above. If `mwp` is blank or 0, then the image will not be resized. (Handy to display 100\% crops.) %b%ib%/b%|Float. %b%l%/b% and %b%r%/b% for left and right. There is also %b%c%/b% for a non-floating (block) centered image. %b%c%/b%|%b%C%/b%aption. The text that is displayed underneath the image. %b%t%/b%|%b%T%/b%itle. The text that displays when you hover your mouse over the image. %b%fic%/b%|%b%F%/b%orce %b%I%/b%mage %b%C%/b%reation for just this one image. For when you are experimenting on layout (i.e. fiddling with different `mwp` values) and don't want to force image creation for the whole file. Optional: `fic=0`, `fic=1` for 'False' and 'True', respectively. `fic` all by itself is 'True'. %b%fa%/b%|%b%F%/b%ile %b%A%/b%ddition. Add this snippit of text to the output filename (before the "." file extension.) So you can use the same source file multiple times at different sizes. `fa=_thum` Like I did for the 'Macro Goodies' image. %/table% Added `MakeTheseJPEGs = png|tif|tiff` variable to config files. To define image types that will be converted to JPEGs. PNGs, for example are robust and are good for originals, but are a lot larger than JPEGs. The default is `png|tif|tiff`. %#%%i%so this is a change to the default behavior.%/i% i.e., before it wouldn't convert PNGs to JPEGs so if you run the current script on your existing `.md` files, any PNG images will now be JPEG images. Which won't break any pages because the generated HTML will also be changed, but you will end up with duplicate PNG and JPEG images. Shrug.%/#% %id clearfloats ht = 'Clears' any floating boxes. Like floating imageboxes. To solve problems with text creeping up where you don't want it to.% ###ClearFloats Use the `\%ClearFloats\%` tag to "clear" any floating boxes. Which I needed to do just now, so the %b%Imagebox%/b% parameters table wouldn't be nestled up in the %b%Imagebox%/b% text, to the right of the floating imagebox. %#%Try it now. Edit the \%ClearFloats\% tag in dogfood.md so it is, say, \%ClearxxxFloats\% and rerun MarkdownWrapper.pl.%/#% %id templatedriven ht = The basic formatting is controlled by 'templates'. So you can, for example, have different templates for regular and mobile sites and generate them all from the same source documents. Like I have done for these documents--see the navigation links at the bottom of the page.% ### Template driven. I'll write more about this when I cover configuration, but note that the single [markup file](DogFood.text) was used to generate ["normal"](http://www.frogymandias.org/FrogDown/DogFood.html), [mobile](http://mobile.frogymandias.org/FrogDown/DogFood.html) and [tablet](http://tablet.frogymandias.org/FrogDown/DogFood.html) versions of the page. (The mobile and tablet versions were built using [jQuery mobile](http://jquerymobile.com/) in the template and are designed for smartphones or tablets.) %id tempvarscss ht = So you can move all your font sizes, color assignments, etc. to a single place in your CSS sheet. (Frogdown is built on CSS sheets. But you don't need to touch them if you don't want to.)% ### Template variables in CSS sheets. Frogdown supports template variables in your CSS style sheets. To enable this, rename your style sheets to have `.csst` for the file extension. Use the `File` variable in your configuration files to tell MarkdownWrapper.pl that the `.csst` files are to be processed and then copied to the destination directory. When MarkdownWrapper.pl sees that the file extension is `.csst` it will do template variable expansion. (If the file extension is `.css` MarkdownWrapper.pl will just copy the .css file.) To define CSS template variables, put a block like ### Start of CSS Variables ### Used by FrogScript MarkdownWrapper.pl _BodyBackgroundColor = #eee _BodyFontColor = Black ### End of CSS Variables ### somewhere in your style sheet. You can put it inside CSS `/* */` comments. Template variables must start with an '_' underscore character. Do not use the leading underscore character when you use the template variable. After defining the template variables, go through your CSS file and put variables wherever you want. Like: body { background-color: %%BodyBackgroundColor%%; color: %%BodyFontColor%%; } Now you can set all your colors and other attributes in one place. %id inlinelinks ht = Regular links, but are easier to type than HTML <a ref=...> style links. And they support hover text.% ###Inline links Links are formed like `\%l ` followed by one, two, or three arguments. If there are more than one argument, separate the arguments with a `|` pipe (vertical bar) character. (Also note that the space after `\%l` is not optional. But spaces before and after `|` delimiters are optional.) Link only: %l http://lipsum.com/% `\%l http://lipsum.com/\%`%br% Link + description: %l Lorem ipsum dolor | http://lipsum.com/ % `\%l Lorem ipsum dolor | http://lipsum.com/\%`%br% Link + description + hover text %l Lorem ipsum dolor | http://lipsum.com/ | Lorem gives good text% `\%l Lorem ipsum dolor | http://lipsum.com/ | Lorem gives good text\%` %id mailto ht = because there is a shortage of email% ###Mailto (to send email) Mailto is formed like `%mailto ` folowed by one or two arguments. The first argument is the email address you want to send to. The 2nd argument is the subject line. \%mailto info@frogymandias.org|The dogfood doesn't taste very good.\% would create a `mailto:` link with the 'mailto' address being `info@frogymandias.org` and the subject line set to `The dogfood doesn't taste very good.` Like %mailto info@frogymandias.org|The dogfood doesn't taste very good.% %clearfloats% %#%Which brings us to.%/#% %id tables ht = Much easier to type than HTML tables% ###Tables Frogdown supports simple tables, like \%table b=1 | cs=0 | cp=3 | bfc | bg = PowderBlue \% Cell one | Cell two Cell one | Cell two \%/table\% %table b=1 | cs=0 | cp=3 | bfc | bg = PowderBlue % Cell one | Cell two Cell one | Cell two %/table% > %table b=0 | cs=1 | cp=3 | bg=#dedede | bfc % !Tag|Description b|%b%B%/b%order (%b%0%/b% is no border, %b%1%/b% = 1 pixel, etc.) cs|%b%C%/b%ell %b%S%/b%pacing. The space, in pixels, between table cells cp|%b%C%/b%ell %b%P%/b%adding. The space, in pixels, between the cell wall and the cell content. bg|%b%B%/b%ackground %b%C%/b%olor of the table. w|%b%W%/b%idth. If specified as a per cent, don't forget to use a backslash to escape the '%'. i.e. %tt%w=90\\%%/tt%. bfc|%b%B%/b%old the %b%F%/b%irst %b%C%/b%ell in a row. Guess why this exists? !|If the first character in a row is a '!', the row will be tagged as <th> The formatting of <th> is defined in your CSS style sheet. I used '!' for the first row of this table (%b%Tag/Description%/b%) to demonstrate how it works. %/table% Umm, while verifying the above definitions, I just read that `CellSpacing` and `CellPadding` are %l not supported in HTML 5| http://www.w3schools.com/tags/att\_table\_cellspacing.asp | which is a bummer %. Which, if true, will break a lot of web pages. But then again, CSS support for tables is %l a big bundle o' fun|http://stackoverflow.com/questions/339923/how-to-set-cellpadding-and-cells pacing-in-css|The lady? Or the tiger? %, so I'm going to gamble that browsers won't drop support for `CellSpacing` and `CellPadding` anytime soon. On the brighter side %l here is a list of HTML color names|http://w3schools.com/html/html_colornames.asp|so you don't need to fool with specifying colors in hexadecimal. As much.% `\%table\%` is a block level Frogdown tag and in general block level Frogdown tags can't be nested. Meaning that you can't put a `\%table\%` in a `\%sidebar\%`. (But you can use native Markdown '`>\ `' block quoting to indent the table. '`>\ \%table...`'. Which is what I just did to indent the tables.) %sidebar sb=bqsidebar|t=Detail% Frogdown block level tags are usually implemented by extracting the text that is delimited by the block level tag (i.e. `\%sidebar\%`), running it through Markdown to convert it to Markdown's dialect of HTML, and then regexxing the HTML that Markdown returned a bit. Ah, this technique doesn't lend itself to nesting very well. %/sidebar% %#%%b%Limitation:%/b% The above %b%Detail%/b% paragraph also partially explains why you can't use any Markdown markup in a table. And (currently) the only Frogdown tags that are supported are for %b%bold%/b% (`\%b\%`%b%bold%/b%`\%/b\%`) and %i%italic%/i% (`\%i\%`%i%italic%/i%`\%/i\%`). `\%table` doesn't run anything through Markdown. And the resultant `` is all HTML, such that Markdown won't touch it.) i.e., you can't use the backtick to indicate `code`. And be careful in general trying to show Frogdown markup. You really need to watch your escaping.%/#% %id nbsp ht = Because you sometimes need a phrase to remain intact and not have a new line jammed in the middle of it.% ###Non break spaces Some\ %b%non-break\ spaces%/b%: '\ \ \ \ \ '%br%('`\\ `' gets converted to '` `'.) Use your browser's "View/Source" to see them.%br% Hmm, backslashs in isolation: 1 '\' 2 '\\' 3 '\\\' 4 '\\\\' Backslashs in isolation in a code block: 1 '\' 2 '\\' 3 '\\\' 4 '\\\\' Other than non-break space, backslash handling is done with Markdown, so see the %l Markdown docs|http://daringfireball.net/projects/markdown/|Look at 'Basics' and 'Syntax'% for particulars. %id namelinks ht = So you can link to specfic parts of your pages. And also auto-generate a Table Of Contents-style list of links at the top of your page. Like you are hovering over right now.% ###Links to internal names Frogdown supports the HTML name and ID attributes. Usage: \%id namelinks\% ###Links to internal names where the first parameter ('`namelinks`') is the HTML 'name' (or 'ID'), followed by the Markdown notation for a third level (in this case) heading. In the spirit of eating your own dogfood, look at the various sources for this page to see how it works. The list of links at the top of the page was automatically generated by `\%id\ \%` tags. Because the HTML 'name' attribute is deprecated and is supposed to be dropped, and because the 'ID' attribute is new and not all browsers supports it, Frogdown splits the difference and uses both. You'll end up (after Markdown has done its magic) with

Links to internal names

To have a list of named links displayed, add a `\%%NameLinks%\%` template variable at the part of the file where you want the list of links inserted. The list of named links that is inserted at the beginning of the file is hardwired to the '`NameLinks`' class. Like: