Utility.Mandown
===============

**Author**: (+Micah Wittman)

## Mandown

### Unique Features of Mandown

The concept of Mandown is to provide a handful of conventions and conveniences around using Markdown to develop 'How To' manuals.

Mandown syntax follows all the rules of [Markdown] (as implemented by the [Showdown] Javascript port) with the exceptions detailed below. The exceptions (_they're a feature, not a bug, really_!) exist to offer a portable, web-centric documentation format.

The design goals are:

> > - **Run-time Rendering** - the power/simplicity of [Markdown] _without_ build-time compiling (dynamic Markdown to HTML happens client-side via Javascript acting on the Mandown source).
> > - **Portability**: Can run from desktop OS file browser (local drive or network file share) _or_ any web server of choice—_as is_.
> > - "Baked-in" **Screenshot UI** features.
> > - **Human Readable Source Displayed in the Browser** viewport if scripting is disabled or not supported.

### Quick Start

To jump right in and start using Mandown:

> > 1. Copy **Utility.Template.Default.html** to a new file, open in text editor of choice and starting writing Markdown.
2. Open in a browser to see the results.
3. To use/share the manual you create, move the whole Mandown application directory to location of choice (local directory, file share or web server).
4. All Manual Files must go in the root of the Mandown application directory, and end in .html
5. Have fun!

### Browser / Platform Quirks

**file://**  
On the Windows platform, Internet Explorer (tested on IE7) by default prompts user to enable active content to enable Javascript to execute in a local file. There is a browser setting to eliminate this prompt, so as to always allow local file active content:

Tools > Internet Options > Advanced (tab) > Security (section) > 
Allow active content to run from files on My Computer* (Set checkmark "on")

That's not the whole story, though. Running from a **Windows network file share**, the prompt can be avoided without users modifying individual computer user profiles _if_ the following declaration is included in said file:

**Note**: if you use the "saved from url" directive method, running from a file share is no problem, but running from C:\\ _is problematic_. You actually **won't** get the "active content" prompt, but functionality is silently disabled (for instance, links manupulated via Javascript look fine, but do nothing when clicked).

So, here are the scenarios:

> > A. If you plan to only run from the local drive (C:\\), change your IE browser setting and _do not_ include the "saved from url" directive.

> > B. If you are only going to host your Mandown manual/s on a file share (and not a local drive), then use the "saved from url" directive and then changing the default browser setting is irrelavant.

> > C. If you need to run both locally and on a file share ... then use Firefox (it _does not_ require the directive _nor_ any browser setting change) and _remove IE from every workstation_ `<smirk>`.

**http://**  
The good news is, running from http: (served from the web, not the file system pseudo web-server) none of the security headaces mentioned above apply.

.........

#### IE

> > Active content issues detailed above. Clicking link to the root Mandown directory opens a Windows Explorer (the file browser—not _Internet_ Explorer).

#### Firefox

> > No active content issues (unlike IE). Clicking link to the root Mandown directory displays the list of files in Firefox itself.

#### Safari

> > No active content issues. But, Safari _does not_ allow browsing the root of the Mandown directory on a local drive, _nor_ does it pass control to _Windows Explorer_.

<a href="#_" name="_Utility_Mandown_StandardFilenaming"></a>
### Content and File Name Requirements

A Mandown manual is a collection of documents which are text files with a .html file extension. A standard document file name must only contain characters that do not require URL encoding (SEE [Tags exception]), and which are permitted by the most common OS filesystems:

> > - *At most*: [0-9a-zA-Z] _and_ $-_.+!'()
> > - *Even safer*: [0-9a-zA-Z] _and_ -_.+

The official recommended convention limits filename characters to [0-9a-zA-Z] _and_ "." _and_ only "+" in (Tag) documents; the format is then dot-notation plus CamelCase:

> > Category.SubCategory.Subject.html

#### Minimal Document Skeleton

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head></head><body><textarea class="md" style="width:750px;height:550px;margin:1% 10% 0 10%">

Document.Foo 
===========

**Author**: (+First Last)

## Foo Title

### Foo Subtitle

Lorem Ipsum foo ...

</textarea><script type="text/javascript" src="scripts/Utility.Scripting.js"></script></body></html>

</div>

The browser parses the Markdown markup in the Mandown file and when it executes the Javascript, it converts all markup wrapped in a `<textarea></textarea>` to HTML.

A fairly straight-forward script/utility application can be written to read and combine all .html files to do things such as produce a "compiled" version of a manual—a single file that's comprised of the content from an assortment of Mandown documents. There is a companion .NET (C#) Windows application (not released yet) that accomplishes just that. The utility mostly just needs to strip out the doctype, html, head, body open and close tags and then combine all the textareas into a single file.

### Linking

Using standard Markdown link syntax:

`[External Document]` ==> [External Document]
    
`[Local Document]`  ==> [Local Document]

`[Screenshot]`  ==> [Screenshot]

Note that one of three (3) icons appear next to a link dynamically and based on the type of link, thus giving a visual cue to the reader. Clicking on the dynamic icon opens the target in a new tab/window (target="\_blank").

[Local Links] have the "![Internal](images/Utility.Internal.png)".

[External Links] use the "![External](images/Utility.External.png)".

[Screenshots] display the "![Screenshot](images/Utility.Screenshot.png)". The standardized dimensions of screenshots is: **800px** wide by **600px** high. The standard size facilitates the Mandown screenshot "[click to resize]" feature.

`[Link to In-Page Anchor]` ==> [Link to In-Page Anchor]

<a href="#_" name="_Utility_Mandown_LinkToInPageAnchor"></a>
**In-Page Anchor Demonstration**

To disable the auto-insertion of the link icon for a hyperlink with a fragment identifier (in-page anchor) SEE [Controlling Link Icon Auto-Insert]: craft the href value with a (hash "#") + (underscore "_") + `Document_Filename_SpecificFragmentIdentifier`:

> > `#_Document_Filename_SpecificFragmentIdentifier`

### Screenshot Syntax

Screenshot Images are coded just like a regular link: **`[Fonts]`**, so no exclamation point as is the case in standard Markdown for inserting a regular image: **`![Graphic X]`(/path/image.jpg)**.

Then for the reference (at the bottom):

> > `[Fonts]`: images/Computer.Fonts.png

This brings it under control of the "IMAGES: Tiny | Small | Large | Hide | Remove" feature. Screenshots also become centered and are clickable to resize.

Mandown uses file extension (.jpg, .jpeg, .gif, .png) detection to determine if a link is referencing an image, at which point it's considered a screenshot image.

So, in our example, say you wanted to show how to access WindowsXP [Fonts] through the control panel.

<a href="#_" name="_Utility_Mandown_ClickToResize"></a>
### Screenshot Interactivity

- Images can be clicked to switch among **tiny** (64 x 40), **small** (400 x 300) and **large** (800 x 600) sizes.
- Once clicked, the image border is highlighted red
- Use the _IMAGES: Tiny | Small | Large | Hide | Remove_ control to switch all screenshots on the page uniformly.

Here's a random image used with Screenshot markup: [Llamas in Peru] (it's public domain and 800 x 600—so actually, not so random after all).

<a href="#_Utility_Mandown_ControllingLinkIconAutoInsert" name="_Utility_Mandown_ControllingLinkIconAutoInsert"></a>
### Controlling Link Icon Auto-Insert

To prevent icon appending per link, begin the URI fragment identifier with an underscore: "#_"

> > - `[Local Document A]: #_Utiity_Mandown_LocalDocumentA`
> > - `[Local Document OtherParagraph]: #_Utiity_Mandown_LocalDocument_ParagraphYWayDownThePage`

> > Note: Including the Document Name in the fragment identifier _is not_ required, but is advantageous (avoids namespace collisions) if/when individual Mandown files are combined into a monolithic manual file.

For `[Screenshot]` markdown, the screenshot image will not be auto-inserted, and a regular hyperlink remains:

> > [Fonts Location]

> > `[Fonts Location]`: images/Computer.Fonts.png#_

<a href="#_" name="_Utility_Mandown_Tags"></a>
### Tags

A Mandown tag using the parenthetical link syntax, but with a "+" character placed after the open parenthesis:

Check out (+Mandown Tags)! Don't delay! Act now! See (+Micah Wittman) for details.

No document reference need be defined because tag always corresponds to a document by its name sake: 
Create a file called: **(+Mandown Tags).html** in the [root] of your Mandown [application directory] (which is where _all_ your regular documents go too).

<a name="_Utility_Mandown_TagsException"></a>
#### Tag Document File Name Characters

Unlike the [standard Mandown file name limitations], a Tag Document file name can (and **must**) have parentheses and the "+" symbol: __(+Mandown Tags).html__ and **may** have spaces.

### References

The list of references (links used in the document) is dynamically generated and sorted and appended to the end of the document at run-time.

----------------------------------------------------
**Created**: 2008-05-25 | **Updated**: 2009-06-17

[External Document]: http://en.wikipedia.org/wiki/Document
   [HTML-Kit]: http://www.htmlkit.com/download/
   [Local Document]: Utility.Markdown.Example.Document.Local.html
   [Screenshot]: images/Computer.HardDrive.Defrag.png
   [Markdown]: http://daringfireball.net/projects/markdown/
   [Showdown]: http://attacklab.net/showdown/
   [Fonts]: images/Computer.Fonts.png
   [Fonts Location]: images/Computer.Fonts.png?i#_
   [Tag]: #_Utility_Mandown_Tags
   [Link to In-Page Anchor]: #_Utility_Mandown_LinkToInPageAnchor
   [Controlling Link Icon Auto-Insert]: #_Utility_Mandown_ControllingLinkIconAutoInsert
   [Llamas in Peru]: http://www.fromoldbooks.org/Montanus-America/pages/00490031-llamas/00490031-llamas-q75-800x600.jpg
   [Internal]: images/Utility.Internal.png
   [root]: ./
   [application directory]: ./
   [Tags exception]:  #_Utility_Mandown_TagsException
   [standard Mandown file name limitations]: #_Utility_Mandown_StandardFilenaming
   [click to resize]: #_Utility_Mandown_ClickToResize