From ec43fd6f3eb486d4493827793834268aeede9211 Mon Sep 17 00:00:00 2001 From: Yann Herklotz Date: Fri, 23 Mar 2018 10:12:20 +0000 Subject: Adding tests for %% (#165) * Going through ps-george list for readmes_examples * separating vanilla markdown into implemented list and design decisions * Updating format * moving build passing * adding link to examples.fmark * Individual README * README updates * Update README.md * Update README.md * Update README.md * Update README.md * typo fix * Adding tests for %% * Adding CLI and markalc docs * remove .html file, can generate from example.fmark * adding js --- README.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 111 insertions(+), 38 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index bfa6806..444b201 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,49 @@ -# FMark -FSharp markdown. +# FMark [![Build Status](https://travis-ci.org/ymherklotz/FMark.svg?branch=master)](https://travis-ci.org/ymherklotz/FMark) +FSharp markdown implementation with additional functionality. -## Test Status +Namely: -[![Build Status](https://travis-ci.org/ymherklotz/FMark.svg?branch=master)](https://travis-ci.org/ymherklotz/FMark) +- Macros +- Includes +- Spreadsheet functionality +- Table of Contents generation +- Citations and footnotes -## Modules +See [example.fmark](examples/example.fmark) for usage examples. + +# How to use + +## FMark Plugin + +Functions: + +- Open Preview (ctrl+shift+M) + +Open a live preview of the HTML that will be generated by FMark. + +- Create HTML File + +Create an HTML file in the same directory as the .fmark file, with .html instead of .fmark. + +## Command Line Interface +``` +USAGE: FMark [--help] [--output ] [--loglevel ] [--format ] [--test []] [] + +INPUT: + specify input file path. + +OPTIONS: + --input, -i CLI flag for input (not necessary, default argument is input.) + --output, -o specify output file path. + --loglevel, -l set the log level ('0:DEBUG', '1:INFO', '2:WARNING', '3:ERROR' ,'4:FATAL'). + --format, -f specify format, by default: html. + --test, -t [] run CI tests. + --help display this list of options. +``` +Note: Markdown generation is incomplete and should only be used for property based testing. + + +# Modules ``` Overall Flowchart: @@ -29,14 +67,22 @@ Source ───> │ Lex and Preprocessor│ ───> Token list ───> 2. [TOCite: Preparsing headers and footers](FMark/src/Common/TOCite/README.md) 3. [Markalc: Spreadsheet functionality](FMark/src/Common/Markalc/README.md) 4. [Main Parser](FMark/src/Common/Parser/README.md) -5. [HTML Generator](FMark/src/Common/HTMLGen/README.md) -## Specification +# Vanilla Markdown -A reference specification for the simple markdown that we are going to follow can be found -at [CommonMark](http://spec.commonmark.org/0.27/). +## Implemented +- HTML passthrough +- Lists +- Links (relative links within file don't work in VSCode, use `Create HTML File` and preview that.) +- Images (images don't work in VSCode, use `Create HTML File` and preview that.) +- Headers +- Styling (bold, italic, bold and italic, strikethrough) +- Paragraphs +- Quotes +- Code blocks +- Tables -A reference implementation of the simple markdown can be found [here](http://spec.commonmark.org/dingus/). +## Design decisions ### Lists @@ -51,12 +97,27 @@ A reference implementation of the simple markdown can be found [here](http://spe * Two spaces as one level of indentation. * A tab, `\t` character will be interpreted as four spaces, therefore two levels of indentation. +### Header + +* All headers must be preceded by two endlines, with an exception made for the first line in a file. + +`\n\n# header\n` is a header, otherwise unless the header is the first line in a file it won't be processed as a header. + +### Styling + +* When using underscores for styling, there must be a space (or endline on the right) on either side in order for it to be recognised. +* Asterisks for styling work as usual. + +e.g. + +`[ ]_em_[ ]`, `[ ]__a strong__[ ]`, or `[ ]_em_$`, `[ ]__a strong__$` + ### Paragraphs A paragraph is some characters that does not match: * CodeBlock * Header -* ContentTable +* ContentTable (Table of Contents object) * List * Quote * Table @@ -64,7 +125,7 @@ A paragraph is some characters that does not match: It terminates with two endlines. Any elements mentions above cannot exist in a paragraph. Otherwise, they will become normal text, and will not be rendered as expected. -# Markdown extensions (not included in standard Markdown) +# Markdown extensions ## Macros @@ -132,7 +193,7 @@ This is the second macro ``` ## Spreadsheet functionality -Spreadsheet functions will evaluate in-place in a table, if they are incorrectly formatted then Markalc will leave the cell unchanged as if it were normal text inside. +Spreadsheet functions will evaluate in-place, if they are incorrectly formatted then Markalc will leave the cell unchanged as if it were normal text inside. To delineate an expression, start the cell with the `=` operator, e.g. @@ -140,7 +201,7 @@ Calcs|39|42| |---|---|---| ||`=6*5+SUM{4,5}`|`=[1,1]+3`| -### Supported Features +### Supported #### Arithmetic @@ -154,8 +215,18 @@ Calcs|39|42| |Addition|`a+b`|a plus b|Property based, all integer inputs. |Brackets|`a+(b-c)`|Specify order of operation.|Unit tested. |Cell References|`[0,2]`|Evaluates to contents of cell specified (row 0, col 2)|Unit tested| -|Range Cell Ref|`[0,0]:[2,0]`|Evaluates to list of cell references.|Unit tested, not fully.| +|Range Cell Ref|`[0,0]:[2,0]`|Evaluates to list of cell references.|Unit tested.| |Keyword Cell Ref|`[col=2,row=0]`|Alternative syntax, order doens't matter.|Unit tested| +|Specify Decimal Places|`=5.333,2`|Comma then a number specifies number of decimal places.|Unit tested| + +##### Cell reference behaviour + +|Referenced cell|Return| +|---|---| +|Contains valid expression `=...`|Contents of cell| +|Does not contain valid expression|nan| +|Is not in table|nan| +|Contains circular reference|nan| #### Functions @@ -174,7 +245,7 @@ Functions support Range Cell References: `[0,0]:[2,0]` will evaluate to `[0,0],[ |Feature|Example|Workaround| |---|---|---| -|Negative numbers using unary operator|`=-a+b`|Subtract number from zero in brackets e.g. `=(0-a)+b`| +|Negative numbers |`=-a+b`|Subtract number from zero in brackets e.g. `=(0-a)+b`| |Integer operations|`=5+2`|All calculations done in floating point.| |Allow formatting around equation|`*=5+2*`|None| |String operations|e.g. Excel CONCAT|None| @@ -205,6 +276,10 @@ FMark supports simple footers and styled references. * One `[^fmark]` inline, and two `[^fmark], some author`. The first will be used. * Reference to non-exist citation will result in `"[Reference: %refID not found!]"` in the HTML generated. +* The list is sorted, with footnotes in order of their numerical IDs first, +References in order of apperance after. Thus the order each explanatory text +comes in the fmark file does not matter. + ### Simple Footers Simple footers have numerical IDs. @@ -245,46 +320,44 @@ Supported data fields |url|Address for website| |access|Date of access for websites, in `yyyy-mm-dd` format| -Pick a style at the beginning, or it will default to Harvard. +Pick a style with `%%RefStyle`, or it will default to Harvard. ``` -%%Style = Harvard +%%RefStyle = Harvard ``` -Then follow `field1= data1, field2= data2, ...` to use references. +Then follow `field1=data1, field2=data2, ...` to use references. + +Spaces around equal sign are allowed, so `f = d`, `f= d`, `f =d` or `f=d` +all have the same effect. + ``` -This is a citation[^Zifan]. This is another[^Eric] one. +This is a citation[^Mark]. This is another[^FMark] one. -[^Zifan], type= Book, author= Zifan Wang, title= Not a real book, year= 2018 -[^Eric], type= Website, author= Eric Wang, title= Not a real website, year= 2017 url= www.example.com/website access= 2018-3-4 +[^Mark], type= Book, author= Mark Smith, title= Not a real book, year= 2018 +[^FMark], type= Website, author= FMark Smith, title= Not a real website, year= 2017 url= www.example.com/website access= 2018-3-4 ``` With Harvard, it will look like this: -> This is a citation(Wang, 2018). This is another(Wang, 2017) one. +> This is a citation(Smith, 2018). This is another(Smith, 2017) one. At the end of the document: -> Wang, Z. (2018) *Not a real book*. +> Smith, M. (2018) *Not a real book*. > -> Wang, E. (2017) *Not a real website*. Available from: www.example.com/website [Accessed 4th March 2018]. +> Smith, F. (2017) *Not a real website*. Available from: www.example.com/website [Accessed 4th March 2018]. if Chicago style is chosen: -> This is a citation(Wang 2018). This is another(Wang 2017) one. +> This is a citation(Smith 2018). This is another(Smith 2017) one. At the end of the document: -> Zifan Wang. 2018. *Not a real book*. +> Mark Smith. 2018. *Not a real book*. > -> Eric Wang. 2017. "Not a real website." Accessed March 3, 2018. https://www.example.com/website - - +> FMark Smith. 2017. "Not a real website." Accessed March 3, 2018. https://www.example.com/website -## TODO -- [ ] Write up formatting for Table of Contents and Citations -- [ ] Math equation rendering (Mathjax) +## Latex maths rendering -### Potential extensions +Fmark includes support for Latex maths rendering. -- Diagrams (Graphviz) -- Autoformatting -- Syntax highlighting -- Error/Warning/Hints highlighting +Surround an equation written in Latex with `$$` in order to use this feature. +Example: `$$2+2=4-1=3$$` -- cgit