
# The "Nom" language and another minimal markup format 

  The world definitely doesn't need another *minimal markup* format.
  That much we know. But "Nom" is good at parsings and transpiling 
  certain grammars, and less good at others (to put it politely).

  As with other "minimal markup" formats, the whole idea is to allow
  the author to write and not get distracted for the fancy formatting
  or the visual clutter of markup languages (like HTML, LaTeX, postscript
  etc). 

  This document, hopefully also serves as a test document for 
  the nom script 

## Emphasis

  Here I am following the "markdown" www.markdownguide.org/basic-syntax 
  style of using *asterixes* "*" to delimit emphasis or a word or 
  also of a phrase. The emphasis cannot extend over several lines. 
  
  Also you can use ** double asterixes** to boldly emphasize text or 
  just a single **word**

  * emphasise text
  >> *italic text* or italic *word*
  >> **bold italic text** or bold italic **word**

  As John McEnroe used to say to the umpires
  **You cannot be serious!!**

## Lists

  There are *no* "lists" at the moment, ordered, unordered or otherwise.
  I will only add them if I really am going to use them.

## Miscelaneous

  * make a horizontal "rule" (line) in the document
  >> >---  (starting the line, end with space)

  Which should look like this (in Html just a <hr/> element).
  >----

  * force a line break, this could be a "poor mans list"
  >> >> (not starting a line)
  
  So we could >> force a break >> and make html put >> a <br/> element
  there.

## Quotes

  Writers of LaTeX and html formatters seem to spend too much time
  trying to produce nice "quotes". It can be nice to change
  *dont* into don't with curly quotes, or <cant> into can't etc.
  A normal apostrophe is like this's.

  I'm you're he's she's it's we're they're aren't  
  can't couldn't didn't doesn't hadn't hasn't haven't 

  Quoted text can occur before all links which changes the link 
  text eg: "The nom command" nom://push

## multiline blockquotes

  multiline quotes begin with """ starting the line. and also
  end with """ any where. These quotes will be rendered as a
  **quotation** .

  Also, we can precede a multiline quote with a line beginning 
  with "*" and that will be formatted as the *citation* for the
  blockquote.

  * a blockquote with a citation, example
  --------
    * John McEnroe, Tennis player
    """ 
      you cannot be serious 
    """
  ,,,,

  Which should look like this.

  * John McEnroe, Tennis player
  """ 
    You cannot be serious!
  """

## Images

  For the css attributes to make the image circular, it 1st needs to
  be cropped to a square. Otherwise it will look like an egg etc
  Images can be included in a document.

  >> enclose the image file name in <> brackets: <imagefile.jpg>
  >> Include a caption with quoted text "An image caption" <imagefile.jpg>

  <doodle.swirl.200wjpg>

  Also "A Doodle with a caption" <doodle.swirl.200w.jpg> 
  Apart from a caption images can have a set of optional attributes
  
  "A doodle with 50% border radius, floating right" <:O:>>:doodle.swirl.200w.jpg>
  "A doodle with 5% rounded corners " <:r:doodle.swirl.200w.jpg> 
  "Image with big rounded corners width '12em' " <:R:12em:doodle.swirl.200w.jpg> 

  * make a circular/ellipse image that floats to the left with width '3em'
  >> <:0:>>:3em:doodle.network.200w.jpg>
  >> <:o:>>:3em:imagename.jpeg> # does the same

  * a circular image with width not specified and a caption
  >> <:O:>>:imagename.jpeg> 

  * make a rectangular image that floats right taking up 30% of page width
  >> <:<<:50%:imagename.jpeg>

  * make an image with its original size
  >> <imagename.jpeg>

  A left floating image small rounded corner image with 20% width
  <:r:<<:20%:doodle.network.200w.jpg>

  The text is supposed to "flow around" floating images.

  A centre aligned image with big rounded corners with 50% width
  <:R:cc:20%:doodle.network.200w.jpg>

  Text should not flow around centre aligned images.

## Image text attributes

  Attributes need to appear in the correct order but all attributes
  are optional.

  * image text attribute order 
  >> <:corners:alignment:width:imagename.ext>

  * valid image text attribute values.
  -----
    O|0|o circular image
    r R small/large rounded corners
    >> << cc float right/ float left/ centre align
    50% 5em 20pt image width specification.
  ,,,,,

  * Demonstrating optional attributes.
  >> <:cc:20%:doodle.swirl.jpg>

  <:cc:20%:doodle.swirl.200w.jpg>

## Code

  One of the points of this format is to document code. So I need 
  to be able to include code in the text document. For *blocks* of 
  code (multiple lines) I start the line with --- (at least 3
  dashes) and end the block with a line starting with ,,, (at least 3
  commas).

  For a single line of code I start the line with >> (with at least 1
  space after)

  The format allows providing a *caption* for the code (above it) 
  by including a line starting with "*" (followed by a space) 
  above the code line or block.

  * a nom script that deletes whitespace
  -------
    read; [:space:] { clear; } 
    print;
  ,,,,,
  
  * run a one line nom script
  >> pep -e "read; print; clear;" -i "abcd"

## links

  To render a url as a link just write it beginning with http:// etc.
  Delimited by spaces. To change the link text include a quoted word
  or phrase before it. 
  
  The formatter makes a link to a local file just with some quoted 
  text and the file name: 
    "The text.tohtml.pss format" text.tohtml.format.txt
     
    "A www link" www.c3.org
  
### Fake schema links 

  Also fake wikipedia links should work with *wp://* and *wp:*

  * make a wikipedia link
  >> "BNF" wp:backus-naur_form

  which should render as "BNF" wp:backus-naur_form


  * make a google search link
  >> google://"distance hobart to colombia"
  >> google:"distance hobart to colombia"
  >> "distance to hobart" google:"distance hobart to colombia"

  google://"distance hobart to colombia" >>
  google:"distance hobart to colombia" >>
  "distance to hobart" google:"distance hobart to colombia" >>
  
  The double quote must immediately follow the :

  I can link to a the documentation for a Nom script language command
  with nom://push or "The Nom language 'push' command" nom://push
  
## Filenames 
  
   Filename like /pars/tr/translate.go.pss should be rendered 
   differently. Also they will be linked if there is some quoted
   text before them.

## Images

  I believe I will use the format "caption text" <image.file.ext>
  or <image.file.ext> for no caption. And maybe even 
  <:10%:image.file.ext> for a width specification
  
## Headings 

 Normally in my documents, I use all capital lines as a first level 
 heading. Like this:
   >> SECTION 3
 For second level headings I use all capitals followed by 4 dots:
   >> SUBSECTION 1 ....

 But for the sake of parsing simplicity, I am just using markdown
 headings with 3 levels. So lines starting with # or ## or ###
 (followed by a space).

## Implementation

 The html formatting is produced by a nom script called 
 file://text.tohtml.pss which is a simplification of an older script
 called "mark.html.pss" mark.html.pss and "A LaTeX formatter" mark.latex.pss

 The "HTML formatter" text.tohtml.pss can be translated into other languages
 such as c, go, java, javascript, perl, python, ruby, and tcl. This can
 be done using the translation scripts in /pars/tr/

 * how to build the html formatter script with go 
 -------
    pep -f /pars/tr/translate.go.pss text.tohtml.pss > text.tohtml.go
    go build text.tohtml.go
    echo "abc" | ./test
 ,,,

## Some tests

 >> code line x
 <this> >> is a file local.html ok.
 "local file" exp.tolist.pss will become a hyperlink | 
 "link text" http://abc.org | 
 file:///eg/palindrome.pss |
 "here>>" www.abc.org/here |

 -------
   ++; ++;
   push; pop; clip; clop; 
 ,,,,,
 
 With some *emphasis<> words* here and *one* word here

 * unknown code
 -------
   ++; ++; >>;
   "is" {
     pop; pop;
   }
 ,,,,,
 
 * refangle the mangle 
 >> x/3 is 6 when 4==x

 >> or else 

 
## a second level heading

some *text* www.bumble.sf.net
  >> for i = 4 { 3,3; }

 "read more" here.txt 

more.
