Intro to Frogdown

Eat your own dogfood

The Dogfood reference is from a quote from Show Stopper!: The Breakneck Race to Create Windows NT and the Next Generation at Microsoft, which describes how Microsoft built Windows NT (which became Windows 2000/XP/Windows 7/Windows 8). They describe "Eating your own dogfood", which means that programmers should use the actual code they are writing. In Microsoft's case, it meant for the programmers writing Windows NT to use Windows NT on their own machines. In other words, "eating their own dogfood."

If you use the code you are writing it tends to bring bugs right front and center. I am using Frogdown to write this page. So...

(Hover over the links for an overview.)

What is Frogdown?

First, Frogdown is a superset of 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 and 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 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 and mobile versions of your web pages.

Frogdown inline markup tags

Look at the original markup file to see the codes. Use your browser's "View/Source" function to see the HTML code that MarkdownWrapper.pl generated.

This text is bold This text is italic This text is bold/italic
(There should have been a line break just before this because I used the %br% tag.) This text is emphasized This text is strong This text is in the typewriter font. See how %tt% handles troublesome text. This text is unadorned. This text is in %code%. See how %code% handles <i>troublesome text</i>.

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.

<div class = "bqsidebar">

Inline images

Donec nec convallis ante. 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.jpg|mwp=25|f=l|t=Left floating%

The parameters are

Tag	Description
i	Image name. Just like <img src="... in HTML. (Can also be img.)
mwp	Minimum Width in Percentage. Just like how it works in the imagebox tag, below.
f	Float. l and r for left and right (as demonstrated above.) There is also c for a non-inline (block) centered image.
t	Title. Is the text that displays when you hover your mouse over the image.

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

Image boxes

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

Tag	Description
img	Image name. Just like <img src="... in HTML. (Can also be img.)
mwp	Minimum Width in Percentage. Explained in the previous paragraph, above. If mwp is blank or 0, then the image will not be resized. (Handy to display 100% crops.)
ib	Float. l and r for left and right. There is also c for a non-floating (block) centered image.
c	Caption. The text that is displayed underneath the image.
t	Title. The text that displays when you hover your mouse over the image.
fic	Force Image Creation 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'.
fa	File Addition. 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.

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.

ClearFloats

Use the %ClearFloats% tag to "clear" any floating boxes. Which I needed to do just now, so the Imagebox parameters table wouldn't be nestled up in the Imagebox text, to the right of the floating imagebox.

Template driven.

I'll write more about this when I cover configuration, but note that the single markup file was used to generate "normal", mobile and tablet versions of the page. (The mobile and tablet versions were built using jQuery mobile in the template and are designed for smartphones or tablets.)

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.

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: http://lipsum.com/ %l http://lipsum.com/%
Link + description: Lorem ipsum dolor %l Lorem ipsum dolor | http://lipsum.com/%
Link + description + hover text Lorem ipsum dolor %l Lorem ipsum dolor | http://lipsum.com/ | Lorem gives good text%

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 info@frogymandias.org

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%

Tag	Description
b	Border (0 is no border, 1 = 1 pixel, etc.)
cs	Cell Spacing. The space, in pixels, between table cells
cp	Cell Padding. The space, in pixels, between the cell wall and the cell content.
bg	Background Color of the table.
w	Width. If specified as a per cent, don't forget to use a backslash to escape the '%'. i.e. w=90\%.
bfc	Bold the First Cell 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 (Tag/Description) to demonstrate how it works.

Umm, while verifying the above definitions, I just read that CellSpacing and CellPadding are not supported in HTML 5. Which, if true, will break a lot of web pages. But then again, CSS support for tables is a big bundle o' fun, so I'm going to gamble that browsers won't drop support for CellSpacing and CellPadding anytime soon.

On the brighter side here is a list of HTML color names

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

Non break spaces

Some non-break spaces: '     '
('\ ' gets converted to ' '.) Use your browser's "View/Source" to see them.

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 Markdown docs for particulars.

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

<div id="namelinks">
<a name="namelinks"></a>
</div>
<h3>Links to internal names</h3>

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:

<ul class="NameLinks">

Options If you want to get fancy...

%id namelinks nl|ht = Text that will display as hover text%
###Links to internal names

ni	Suppress storing the ID/Name info in the IDs file (below).
nl	Suppress storing the ID/Name info in the list of links. Say, if the list of links will be appear right next to something you are naming, you really don't need a link to it.
nht	No Header Text. Don't print the header text. If all you wanted to do was establish a name/ID so you could link to it, but didn't want to display a header right here.
ht	Hover Text. (Hover text is implemented as the HTML <title="..."> tag. Because most browsers will display <title="..."> text as hover text.)
l	Real Link. Link to this (presumed external link) instead of to an #internal link. Assumed nht. So you can add a link to an external page (site) instead of to an internal #id.

IDs file MarkdownWrapper.pl will also write a list of the names it finds to an external file that can be processed by separate programs. (Say, to generate a table of contents for a group of pages.) The IDs files will be located in the FLinks directory of your authoring directory. It will be named with the basename of the .md file with a .txt file extension. (i.e., the IDs file for this page is FLinks/DogFood.txt) It will be formatted like:

### Start of Variables ###
# Created by MarkdownWrapper 0.31  2013-07-07

PageTitle = Intro to Frogdown
PageID = dogfood
Filename = DogFood.html
JustDir = Frogdown/
RelPathToHome = ../
Fields = ID|HeadingLevel|Description

### End of Variables ###
frogdown|3|What is Frogdown?
frogdowninline|3|Frogdown inline markup tags
sidebar|3|Sidebars

etc.

Limitation: Because of a finicky regex, you can't have any trailing spaces at the end of a %id ... tag. If you see any %id ... tags appearing in the text and not being rendered properly, look for trailing spaces after the final '%'.

Limitation #2: Does not work on the mobile/tablet pages. jQuery Mobile works differently than regular HTML for internal links. And mobile browsers don't seem to display hover text. More work is needed. For now, the clumsy workaround is that if the IsMobile variable (in your .cfg files for anything that will be using jQuery Mobile) is true, then %%NameLinks%% will be ignored--the list of links to internal names will not be inserted. But the IDs file will be created regardless.

(This will be elaborated on in the future.)

User definable <span> tags.

Add a section like

### Start of Span Variables ###
# User definable <span> tags.

# Must escape '=' as '\='

# Any classes must exist in your .csst files.
_Button = <span class\="button">
_Warning = <span style\="color: red; font-weight:bold;">

### End of Span Variables ###

to your .cfg files. (Note the '\=' escaping.) Then you can use like

Don't press the %warning%Eject%/warning% button.

Will display like

Don't press the Eject button.

%Button% and %warning% were previously defined in earlier versions but were hard-wired into the logic of MarkdownWrapper.pl The logic looked extendable, so... However, this only works for <span> tags because the <span> tag is hardwired into the logic.

Some examples of how to use _<span>_ Note that <span> is more of a CSS type thing, so you use CSS syntax, not HTML syntax when adding styling. (Google 'CSS'...)

Verse tag

%verse% block tag that acts like HTML <pre> except that it doesn't change the font to monospace. But does preserve line breaks and leading spaces. So you can type stuff and preserve line breaks without needing to stick a %br% at the end of each line. And the above mentioned non-break space isn't needed to preserve leading spaces at the beginning of lines in a %verse% block.

%verse%
I am His Majesty's dog at Kew.
Pray tell me, sir, whose dog are you?  
   -- %i%Alexander Pope%/i%
%/verse%

Displays like

	Options
c	Center the entire verse
f	Select from the following Fonts (CSS style) i.e., f=Garamond, Palatino, Times New Roman, serif
s	Font Size i.e., 12 px, 120% (Make sure to escape the '%' with a '\' backslash, like '120\%'.)
lm	Left Margin sets the left margin. Again, CSS style. 'lm = 3em' is a good start.
Style	Copies any other misc. CSS styles verbatim into the style section of the <p> tag that encloses the verse.
Class	Points to a Class that is in your CSS sheet. This class must, of course, exist. The default is 'verse' (If the Class doesn't match up with a class in your CSS sheet, then nothing changes.)

Thusly,

%verse lm = 4em%

yields

And going hog wild with

%verse c|Class = Verse2|f=Garamond, Palatino, Baskerville, Times New Roman, Times, serif|s=150\%|
  style = font-weight: bold; color: green%

will get us

MarkdownWrapper.pl generated this HTML for the above:

<div>
<p style ="text-align: center; font-family: Garamond, Palatino, Baskerville, 
  Times New Roman, Times, serif; font-size: 150%; 
  font-weight: bold; color: green" Class = "Verse2">
I am his majesty's dog at Kew;<br>
Pray tell me, sir, whose dog are you?<br>
&nbsp;&nbsp;-- <i>Alexander Pope</i><br>
</p>
</div>

which maybe clarifies how this tag works. (Well, Class = "Verse2" doesn't really do anything because there isn't any 'Verse2' class defined in the CSS sheet. Let's treat this part as a user excercise.)

Be careful when specifying fonts. See the Complete Guide to Pre-Installed Fonts in Linux, Mac, and Windows. And read Better CSS Font Stacks This also applies to the next section:

To be implemented

Logical formatting with Frogdown The goal is to have Frogdown equivalents do as much Markdown (and raw HTML) formatting as possible so future "Frogdown to ..." converters will be possible. (And "... to Frogdown" converters will also be possible.)

Extending 'Links to internal names' for TOC type generation. Still mulling this over.

Making %##%(Text to be comment out)%/##% comment tags to totally delete the "comments" (instead of just delimiting them with <!-- and --> to deal with commenting out text that includes comments. (4/17/2022 is now implemented)

Dealing with lists, etc. better.

<ul>
    <li>Item one
    <ul>
        <li> Item A
        <li> Item B
    </ul>
    <li>Item two
</ul>

4/17/2022 Hmm, nested lists seems to work now. Might have been recent change to md5_hex($char) escaping. (Frogdown had been using the exact escaping that Markdown itself was using. Now it isn't.)

Keep watching this document.

Comments? Write to info@frogymandias.org

(Created with MarkdownWrapper 0.50 2022-04-28)