ef3d0c3e/nml
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update readme

Browse source
This commit is contained in:
ef3d0c3e 2024-07-19 11:57:09 +02:00
parent 5b39cfa789
commit f89259eef5
1 changed files with 73 additions and 883 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

956
readme.nml
View file

@ -1,896 +1,86 @@
#:Inc resources/template.nml
#+Title NML -- The nice markup language!
#+TOC Table of content
@html.page_title = NML -- Readme
@html.title = NML -- The nice markup languge!
@'html.css = style.css
%%(define (spoiler-text title content)
(string-append "{{{<details><summary>}}}" title "{{{</summary>}}}\n"
content
"{{{</details>}}}")
)
(define (make-anchor-link name)
(string-append "[" name "](#" (nml-html-get-anchor name) ")"))
%%
@tex.main.fontsize = 9
@tex.main.preamble = \usepackage{xcolor} \\
\definecolor{__color1}{HTML}{d5d5d5} \\
\everymath{\color{__color1}\displaystyle}
@tex.main.block_prepend = \color{__color1}
#+DefaultUnorderedBullet •
# Paragraphs
# Preamble
Blank lines (or multiple `\\n`'s) create new paragraphs!
NML is a markup language designed to be featureful. It integrates features from other markup language, such as MarkDown and LaTeX. And it also features an extension language to extend the language or do computations.
It currently is in an unstable stage. You should expect bugs and incomplete feature (CXXABI, NML Object, and Highlight caching).
# Building
NML uses CMake as it's build system. To build NML, you must create a directory where the program will be compiled =build=.
NML requires =libguile= (dev lib) to be installed.
NML can be installed by moving it to your path. Note that this is not a requirement.
Here is a summary:
```sh
# Clone nml
git clone https://github.com/ef3d0c3e/nml
cd nml
mkdir build && cd build
# Build
cmake ..
make
# (Optional) Install nml
mv nml (to a directory in $PATH)
```Plain Text, Example
First paragraph :: first '\n'
:: second '\n'
Second paragraph
```
## Additional requirements
# Lists
In order to enable LaTeX processing, you must install =latex2svg= (found in =nml/readme=) into your path.
Numbered lists `-`:
- first
- second
- third
# Syntax
## Definitions
Unnumbered lists `\*`:
* A
* B
* C
NML allows defining internal variable that can be used inside a document, or by NML itself.
```c
#+VariableName Value
→ %VariableName% : "Value"
NML also supports list nesting of multiple kinds:
* first
* second
*- 2.1
*- 2.2
*-* even more nested
* third
#+SplitDefinition ValueLine1\
ValueLine2
→ %SplitDefinition% : "ValueLine1ValueLine2"
# Style
#+MultiLine First\\
Sec\
ond\\
Third
→ %MultiLine% : "First\nSecond\nThird"
NML supports markdown-based text styling:
* \*\*bold\*\* -> **bold**
* \*italic\* -> *italic*
* \__underline\__ -> __underline__
* \`emphasis\` -> `emphasis`
Some additionally supportd text styling
* \`\`inline code\`\` -> ``inline code``
* \`\`C, int main()\`\` -> ``C, int main()``
# Code
```[line_offset=64] C, Some C code
int main(int argc, char** argv)
{
return 0;
}
```
Calling a defined variable is done by putting the variable's name between two =\%='s^{{Called variables are parsed, so they can contain more NML code, or even new variable definitions}}.
*Note*: If a variable is already defined, defining a new variable with the same name will overwrite the first variable
```c
#+MyName Robert
#+MyName John
→ %MyName% : "John"```
**Path-aware definitions**
It may be useful to have definitions that correspond to the location of a file. However, when including a NML document from another directory, the relative location of this file will change.
You can create path-aware definitions by adding a ='='s after the variable's name.
```txt, Example use case
[File] My NML template file.nml
| #+Picture image.png
| #+PictureAware' image.png
[File] image.png
[Folder] My project
| [File] Project.nml
| | #:Inc ../My NML template file.nml
| |
| | %Picture% → image.png (wrong)
| | %PictureAware% → ../image.png (correct)
```
**Proxy definitions**
It is possible to create a definition based on other variables. While using a clever tricks by defining a variable that evaluates to another one, this technique also work in contextes where variables aren't evaluated! (ex: calling a variable from scheme)
```c, Proxy variable example
#+A My variable...
#+R& A :: References A
%R% :: → "My variable..."
#+A Changed!
%R% :: → "Changed!"
```
The syntax consists of adding a =&='s after the variable's name.
**Copy definitions**
It is also possible to create variable that will copy the content of another variable at a given moment.
This is what copy definitions are for!
```c, Copy defitinions example
#+A My variable...
#+R% A :: Copy of A
%R% :: → "My variable..."
#+A Changed!
%R% :: → "My variable..."
```
The syntax consists of adding a =\%='s after the variable's name.
## Raws & Inline raws
Sometime it is convinient to add code that the compiler will leave as-is so that the target output document can be interacted with without having to go through NML.
This feature can be abused in order to extend the language and create new syntax elements (see %(make-anchor-link "DefStyle")%, %(make-anchor-link "DefPresentation")% and %(make-anchor-link "DefProcess")%)
**Inline raws**
Inline raws can be used inside a paragraph, applied on text for instance.
The syntax goes as follow: =\{{{content}}}=
For instance, raws can be used to add colored text: {{{<a style="color:red">Red text</a>}}}.
This was done using the following: =\{{{<a style\="color:red">Red text</a>\}}}=
But using a bit of scheme, we can make it easier to use:
```c
%%(define (colored-text color text)
(string-append "{{{<a style=\"color:" color "\">}}}" text "{{{</a>}}}"))%%
```
%%(define (colored-text color text)
(string-append "{{{<a style=\"color:" color "\">}}}" text "{{{</a>}}}"))%%
Usage: =\%(colored-text "green" "Green text")\%= **→** %(colored-text "green" "Green text")%
**Regular Raws**
Regular raws act like inline raws except that they are not meant to be used inside a text paragraph.
## Comments
You can add comments to NML documents by putting =\::='s before your comment.
## Code fragment
It is possible to add code fragment to your documents. To make your life easier, code fragment support a variety of options such as importing code from a file or automatic highlighting.
Here is the syntax for a simple code fragment:
```c
\```language (write txt for none)
Your code here
\```
```
Additionaly, you can add a name for your code fragment, which will display as a title:
```c
\```c, My C Program
[...]
\```
```
**Code style**
In order to use code fragments, you must first have a code style. This is a file used by =source-highlight= to set colors of highlighted code.
Currently, this file is using [nml.style](nml.style) a color code that looks relatively well with NML's default colors.
To set which file to use for =source-highlight=, you have to modify the =%CodeStyle%= variable
**Including code from another file**
Instead of copy-pasting you code into code fragments and end up with long NML files, you can import text from a source file rather easily.
The syntax for importing code is =#:Inc path=.
Below is the result given by importing the [fizz.cpp](./resources/fizz.cpp) file:
```cpp, My C++ fizzbuzz
#:Inc ./resources/fizz.cpp
```
This is given by:
```c
\```cpp, My C++ fizzbuzz
\#:Inc ./resources/fizz.cpp
\```
```
Additionaly, you can import a selected number of lines from a file.
The syntax syntax is =#:Inc path, start, n=, where =start= is the starting line, and =n= is the number of lines to import.
```cpp, Lines 8 to 13 of fizz.cpp
#:Inc ./resources/fizz.cpp, 8, 6
```
This is given by:
```c
\```cpp, Lines 8 to 13 of fizz.cpp
\#:Inc ./resources/fizz.cpp, 8, 6
\```
```
## Includes
You can include other document's content with the include mechanic.
This can be used to include a template document that sets a special footer, style or anything you want to have in all of your documents.
Including a document works as if copy-pasting the content of the document inside the current document.
For instance, we can include the =[include.nml](resources/include.nml)= document inside this one:
#:Inc resources/include.nml
*Note*: Including another document will import (and overwrite) variables, figures, external references, custom styles, custom presentations and custom processes.
For instance, including document =include.nml= imported the =IncludedVar= variable:
*\%IncludedVar\%* **→** %IncludedVar%
The syntax is as following:
```c, (on an empty new line)
\#:Inc path
```
## Lists
**Unnumbered**
NML supports numbered and unnumbered lists out of the box, lists can also be nested indefinitely.
#+Bullet •
* This an unnumbered list
* It has another unnumbered list nested into it!\\
#+Bullet →
** Nested!
%(spoiler-text "NML Code" "```c
#+Bullet •
* This an unnumbered list
* It has another unnumbered list nested into it!\\\\
#+Bullet →
** Nested!
```")%
Lists' bullets can be customized, using the =Bullet= variable. It's also possible to set a custom style for the compiler using =BulletStyle=.
The default =Bullet= for unnumbered lists is =\*)=, which is ugly, because it's meant to be changed!
The =Bullet= variable resets at the end of every unordered list. Changing =DefaultUnorderedBullet= is a good way of ensuring a default unordered bullet.
**Numbered**
Likewise, lists can also be numerated:
- First element
- Second
-- Second A)
-- Second B)\\
#+Bullet •
-* Second ???
- Third
%(spoiler-text "NML Code" "```c
- First element
- Second
-- Second A)
-- Second B)\\\\
#+Bullet •
-* Second ???
- Third
```")%
Numbered lists' bullets can also be customized:
#+Bullet i/
- First element
- Second\\
#+Bullet A)\\
#+BulletStyle color:red
-- Second A)
-- Second B)\\
#+Bullet •
-* Second ???\\
#+BulletCounter 5
- Fifth
%(spoiler-text "NML code" "```c
#+Bullet i/
- First element
- Second\\\\
#+Bullet A)\\\\
#+BulletStyle color:red
-- Second A)
-- Second B)\\\\
#+Bullet •
-* Second ???\\\\
#+BulletCounter 5
- Fifth
```")%
The =BulletCounter= variable overwrite the current counter to have custom numbered indices lists.
In order to be valid, a =Bullet= variable for numbered lists must contain at least one of the following character:
- =1= For numerical numbering (1, 2, 3, ...)
- =a= For lowercase alphabetical numbering (a, b, c, ...), up to 26
- =A= For uppercase alphabetical numbering (A, B, C, ...), up to 26
- =i= For lowercase roman numbering (i, ii, iii, ...), up to 3999
- =I= For uppercase roman numbering (I, II, III, ...), up to 3999
- =v= For lowercase roman numbering, but =i='s are replaced by =•='s (•, ••, •••, ...), up to 3999
The default =Bullet= for numbered lists is =1.=, which produces bullets as shown above
Other characters in =Bullet= will not be touched and be added to the final bullet (e.g =<1i.>= gives =<1i.>=, =<2i.>=, =<3i.>=...)
The =Bullet= variable resets at the end of every ordered list. Changing =DefaultOrderedBullet= is a good way of ensuring a default ordered bullet.
*Note*: In future versions of NML, there will be a possibility to invoke a scheme procedure in order to have custom bullets.
## Sections
Sections basic elements in NML, they work as delimiters and have a name. Depending on the compiler and settings, a list of sections might be produced somewhere in the resulting document (such as a *table of content*) and might be numbered.
```c
# Sections
## SubSection
### SubSubSection
##* This subsection is not numbered
###** This SubSubSection is not numbered and will not appear in the TOC
```
**Numbering format**
Sections numbering is based on the current number of sections and previous sections.
By default, numbering separates all numbers with a =.='s. You can define a scheme procedure that will output a custom formatting.
Define =OrderedSectionFormatter= or =UnorderedSectionFormatter= to the name of a lisp procedure. Both procedures should take two argument, the first being the section's number and the second being the section stack.
```c
%%(define (ordered-formatter num sstack)
"<...>")
(define (unordered-formatter num sstack)
"<...>")%%
#+OrderedSectionFormatter ordered-formatter
#+UnorderedSectionFormatter unordered-formatter
```
**Specifity in HTML**
In HTML, sections have a link that is used to create direct link referring to a unique section
To change the content of this lick, modify the =SectionLink= variable, the default in HTML is =[link]=.
You can also set where this link will show by modifying the =SectionLinkPos= variable:
* Set it to =before= to have it shown before the section's name
* Set it to =after= to have it shown after the section's name
* Set it to =never= to disable it
*Note*: below are the settings used in this document:
```c
#+SectionLinkPos before
#+SectionLink #
```
## Text styles
You can add style to text to make **bold**, *italic*, __underline__ and =verbatim= text.
The syntax goes a follow:
* =\*\*Bold text\*\*= **→** **Bold text**
* =\*Italic text\*= **→** *Italic text*
* =\__Underline text\__= **→** __Underline text__
* =\=Verbatim text\== **→** =Verbatim text=
It is possible to create your own text styles, see the %(make-anchor-link "DefStyle")% section.
## Ruler
===
You can add a 'ruler' to a document that acts as a horizontal separator.
To create a ruler you have to put three (or more) =\=='s signs on an empty line.
```c
===
```
## Figures
Your documents will ofter need figures. NML supports three main types of figures: pictures, videos and audio^{{Of course, depending on the target format, some figures types may not be supported. For instance, videos and audio are not supported for PDF documents.}}.
NML tries to handle figures so that they can be interacted with or referenced in other paragraphs.
For instance, below is a picture:
![figure1](resources/fig1.jpg) Optional figure description
This picture is internally named =figure1=, meaning it can be referenced inside a paragraph using it's internal name: §{figure1}
```c, Defining a figure (on an empty new line)
![internal reference name](figure path.extension) Optional description
```
```c, Referencing a figure
§{internal reference name}
```
## Links
Similarly to figures, your document may contains links.
For instance:
* My [github](https://github.com/ef3d0c3e)
* My [e-mail](mailto:ef3d0c3e@pundalik.org)
```c, Links syntax
[Link text](protocol://link url)
```
## Annotations
You can add inline annotations to your documents, like so^{{This is an *annotation*}}.
#+Annotation My fizzbuzz solution
Or like this^{{===
My super cool fizzbuzz
```cpp, Source code
#:Inc ./resources/fizz.cpp
```
===}}.
#+Annotation [note]
The syntax for annotations is as following:
```c
^{{Annotation content
Can be split on multiple lines}}
```
By default annotations will appear with the =[note]= label.
You can change this by modifying the =Annotation= variable
%(spoiler-text "NML code" "```c
You can add inline annotations to your documents, like so^{{This is an *annotation*}}.
#+Annotation My fizzbuzz solution
Or like this^{{===
My super cool fizzbuzz
\\```cpp, Source code
\\#:Inc ./resources/fizz.cpp
\\```
===}}.
```")%
## External references
Like Wikipedia pages, documents can contain external references -- references to external resources.
For instance, here is an external reference to the Wikipedia article "Green terror"§[Green terror Wikipedia article][Wikipedia contributors](https://en.wikipedia.org/wiki/Green_terror).
The syntax is as following:
```c
§[Clickable reference description][Reference authors](protocol://reference hyperlink)
```
**Reference section**
External references will generate a 'section' called =Reference= that will contain every references of the document.
You can view a reference in this reference ection by clicking on the number generated.
* The name of the reference section is defined in the variable =ExternalRef=
* Using multiple times the same reference will create a single entry into the reference section (and they will also share the same number)
%(spoiler-text "NML code" "```c
§[Green terror Wikipedia article][Wikipedia contributors](https://en.wikipedia.org/wiki/Green_terror).
```")%
## Quotations
In NML document you can add quotations using the following syntax:
```c
>Quotation
>continued on this line
>[Quote's author]
```
>Quotation
>continued on this line
>[Quote's author]
*Note*: The quote's author part is optional and can be placed anywhere in the quote
## Presentation
Presentation refers to syntax elements that set how to display a paragraph (centering, boxed, ...)
**Centering**
To center things, you have to put them between two brackets (=\[[= and =]]=):
```c
[[Centered text!]]
```
Gives:
[[Centered text!]]
**Boxed**
To put a box aroung things, you have to put them between three brackets (=\[[[= and =]]]=):
```c
[[[Boxed text!]]]
```
Gives:
[[[Boxed text!]]]
**Left line**
To put a line on the left of things, you have to put them between these characters =\[[|= and =|]]=:
```c
[[|This text has a line on its left!|]]
```
Gives:
[[|This text has a line on its left!|]]
# LaTeX
:: Store and reset tex-related variables
#+TexPreambleSave% TexPreamble
#+TexPreamble
#+TexPrependSave% TexPrepend
#+TexPrepend
NML has built-in support for LaTeX. However, it requires that you install a modified [latex2svg](./latex2svg) to your =PATH= and that you install its requirements, more information on the program's [GitHub page](https://github.com/Moonbase59/latex2svg).
## Setup
Compiled LaTeX files are stored in a folder to speed-up document compiling. By default this folder is called =tex=, however you can change it's name using the =--tex-directory= argument when executing NML.
Also, the folder won't auto-generate, you will have to manually create it for the tex processing to be enabled.
In order to write inline math LaTeX in NML, you have to use the followin syntax: =\$LaTeX math code\$=
For instance: =\$1+1\=2\$= **→** $1+1=2$
As you can see, by default, LaTeX will appear black, which is not too visible on a dark background.
You can change the text color by defining the following variables:
```c
#+TexPreamble \
\usepackage{xcolor, amsfonts}\\
\definecolor{__color1}{HTML}{c5c5ce}
#+TexPrepend \color{__color1}
```
#+TexPreamble \
\usepackage{xcolor, amsfonts}\\
\definecolor{__color1}{HTML}{c5c5ce}
#+TexPrepend \color{__color1}
Now, LaTeX code will appear with a more visible color: $\sum_{k \in \mathbb N^*} \frac{1}{k^2} = \frac{\pi^2}{6}$
:: Revert tex variables to match the ones in template.nml
#+TexPreamble% TexPreambleSave
#+TexPrepend% TexPrependSave
Compiled LaTeX files are stored in vector graphic format (=svg=).
* The files with suffixes =_m= are for %(make-anchor-link "Inline math")%
* The files with suffixes =_l= are for %(make-anchor-link "Inline math line")%
* The files with suffixes =_n= are for %(make-anchor-link "Regular LaTeX")%
* The files with suffixes =_i= are for %(make-anchor-link "LaTeX include")%
## Inline math
Inline math is the default LaTeX mode for writing equations, it is the same as typing your code between two =\$='s in a regular LaTeX file.
The syntax is simply =\$LaTeX math code\$=.
For instance:
* =\$\sin \frac{\pi}{4} \= \frac{\sqrt 2}{2}\$= **→** $\sin \frac{\pi}{4} = \frac{\sqrt 2}{2}$
* =\$x^n (T\*R) \= \sum^{n}_{k\=0} \begin{pmatrix}n \\ k\end{pmatrix} (x^k T) \* (x^{n-k} R)\$= **→** $x^n (T*R) = \sum^{n}_{k=0} \begin{pmatrix}n \\ k\end{pmatrix} (x^k T) * (x^{n-k} R)$
While in certain cases, inline math may have trouble respecting line-height and alignment, it is very handy and easy to use.
## Inline math line
Inline math line is the same as inline math, except it is equivalent to typing LaTeX code between two =\$\$='s.
The syntax is simply =\$\$LaTeX math code\$\$=.
## Regular LaTeX
Regular LaTeX is the same as directly typing in LaTeX. With this you can create, for instance, LaTeX plots, graphes or tables directly in your NML document.
The syntax is =\$|Your LaTeX|\$=. Below is an example:
[[$|This is LaTeX typed directly into \textbf{NML}!|$]]
Combining with =#:Inc=, you can import LaTeX from other files:
[[
#:Inc ./resources/plot.tex
]]
## LaTeX related variables
LaTeX processing uses 3 different variables:
* =TexFontSize= (default: =12=) This sets the font size (in pt) of the generated LaTeX.
* =TexPreamble= This is a preamble used before the content
* =TexPrepend= This will be appended at the begining of the content of every LaTeX file.
* =TexAppend= This will be appended at the end of the content of every LaTeX file.
You should look into [template.nml](./template.nml), the file where the LaTeX settings for this document are.
# User-Defined Syntax
NML offers the possibility to create you own syntax with the help of scheme.
## DefStyle
DefStyle allows you to define new text style.
The syntax is:
```c, (on an empty new line)
#:DefStyle syntax-name regex
```
In order to define how this new style works, you will have to define two new scheme procedure.
Given that your new syntax is called =my-style=, you will have to define procedures =(my-style-begin)= and =(my-style-end)=.
They both will return a string and the *begin* procedure is called when your style begins, and the *end* procedure is called when your style ends.
Below is an example style, we define a strikethrough text style:
```c, Example strikethrough style
%%(define (strikethrough-begin)
"<s>")
(define (strikethrough-end)
"</s>")%%
#:DefStyle strikethrough ~
```
%%(define (strikethrough-begin)
"<s>")
(define (strikethrough-end)
"</s>")%%
#:DefStyle strikethrough ~
The result:
* \~Strikethrough text\~ **→** ~Strikethrough text~
**More complex styles**^{{This section contains informations not yet detailed in this readme. Such as the NML Object interface for Guile.}}
Additionaly, you can define a =(my-style-apply elements)= procedure. This procedures takes the content of the document on which the style is used and returns the new content after modifications.
This can be used to make some more complex styles:
```c, Alternating color custom text style
%%(define (alternating-begin)
"")
(define (alternating-end)
"")
(define (alternating-apply elems)
(let ((result '()))
(for-each (lambda (x)
(if (nmlo-is-text x)
(let ((str (nmlo-text-content x)))
(string-for-each-index (lambda (i)
(if (even? i)
(set! result (append result (list
(list 16 "<a style=\"color:orange\">")
(list 0 (string (string-ref str i)))
(list 16 "</a>"))))
(set! result (append result (list
(list 16 "<a style=\"color:red\">")
(list 0 (string (string-ref str i)))
(list 16 "</a>"))))
))
str))
(set! result (append result x)))
)
elems)
result))
%%
#:DefStyle alternating @
```
%%(define (alternating-begin)
"")
(define (alternating-end)
"")
(define (alternating-apply elems)
(let ((result '()))
(for-each (lambda (x)
(if (nmlo-is-text x)
(let ((str (nmlo-text-content x)))
(string-for-each-index (lambda (i)
(if (even? i)
(set! result (append result (list
(list 16 "<a style=\"color:orange\">")
(list 0 (string (string-ref str i)))
(list 16 "</a>"))))
(set! result (append result (list
(list 16 "<a style=\"color:red\">")
(list 0 (string (string-ref str i)))
(list 16 "</a>"))))
))
str))
(set! result (append result x)))
)
elems)
result))
%%
#:DefStyle alternating @
The result:
* =\@Alternating color text!\@= **→** @Alternating color text!@
# Scheme
NML uses the GNU Scheme language to extend documents.
You can define and call scheme procedure inside nml documents in order to extend NML.
## Inline scheme
You can use scheme as a handy tool for inline operations.
For instance you can use it to output the result of calling a procedure.
When using inline scheme, the SCM object returned by the procedure is converted as a string for display.
Example:
- =\%(- 10 (\* 2 2) (/ 60 (+ 3 4 4)))\%= gives %(- 10 (* 2 2) (/ 60 (+ 3 4 4)))%.
- =\%(string-append "Hello" ", " "world" "!")\%= gives %(string-append "Hello" ", " "world" "!")%
- =\%(exp (sqrt -1))\%= gives %(exp (sqrt -1))%
The syntax is simply =\%(scheme-expression)\%=
## Global scheme
It's also possible to write scheme code without having to worry about returning a SCM object.
This is usualy better for defining procedures or variables.
The syntax consists of putting the scheme code inside two =\%='s
For instance, we can define the factorial procedure as follow:
```lisp
%%(define (! n)
(if (= n 1)
1
(* n (! (- n 1)))))%%
```
%%(define (! n)
(if (= n 1)
1
(* n (! (- n 1)))))%%
And then we can call it using inline scheme: =\%(! 5)\%= **→** %(! 5)%.
## Custom procedures
NML defines new scheme procedures for convennence.
Also, in order to interact with NML, scheme has access to procedures and objects related to NML.
Below is a list of important procedures and objects:
**Variable related:**
* **(nml-var-defined *var-name*)** : Checks if a NML variable with name =var-name= is defined in current document.
* **(nml-var-get *var-name*)** : Gets content of NML variable with name =var-name=, returns =nil= if variable does not exist.
* **(nml-var-get-default *var-name* *default-value*)** : Gets content of NML variable with name =var-name=, returns =default-value= if variable does not exist.
* **(nml-var-define *var-name* *var-value*)** : Defines new NML variable with name =var-name= and content =var-value=. Procedure returns true on success. Both parameters must be strings, otherwise the procedure returns false.
**Document related:**
* **(nml-doc-parse *doc-path* (*doc-inherit* *doc-data*))** : Parses a NML document located at =doc-path=. Additionaly, another document and data may be passed to inherit certain attributes. \
Parsing will use of =nml-current-parser= as a parser. Will returns a NML document on success.
* **(nml-doc-compile *doc* *compiler-name* (*tex-path*))** : Compiles a NML document (=doc=) into a string, using compiler =compiler-name=.
* **nml-current-doc** Current document instance
* **nml-current-data** Current data instance
* **nml-current-parser** Current parser instance
**Utilities:**
* **(nml-num-roman *number* *roman-base*)**: Converts a number (=number=) to roman numeral, using =roman-base= as an alphabet. \
Exemple: =\%(nml-num-roman 14 '("M" "CM" "D" "CD" "C" "XC" "L" "XL" "X" "IX" "V" "IV" "I"))\%= **→** %(nml-num-roman 14 '("M" "CM" "D" "CD" "C" "XC" "L" "XL" "X" "IX" "V" "IV" "I"))%.
**Utilities for HTMLCompiler:**
* **(nml-html-get-anchor *name*)**: Gets anchor name of =name= as a string.
* **(nml-html-format *text*)**: Formats =text= to be HTML safe.
**Filesystem Utilities:**
* **(nml-fs-path *path-name*)**: Gets path representing =path-name= (relative to current working directory)
* **(nml-fs-exists *path*)**: Returns whether or not =path= exists
* **(nml-fs-is-file *path*)**: Returns whether or not =path= is a file
* **(nml-fs-is-dir *path*)**: Returns whether or not =path= is a directory
* **(nml-fs-filename *path*)**: Returns ending filename of =path= (=src/test.c= **→** =test.c=)
* **(nml-fs-fullname *path*)**: Returns name of absolute path of =path=.
* **(nml-fs-map *proc* *path*)**: Applies procedure =proc= to every elements of =path=
**String Utilities:**
* **(string-tail *string* *n*)**: Returns a new string containing the =n=-th last characters of =string=.
* **(string-ends-with *string* *suffix*)**: Returns whether or not =string= ends with =suffix=
* **(string-starts-with *string* *prefix*)**: Returns whether or not =string= starts with =prefix=
## Scheme example
**Compiling a NML document from another NML document**
```lisp
(define (write-file path content)
(if (and (nml-fs-exists path) (not (nml-fs-is-file path))) 'nil)
(call-with-output-file (nml-fs-fullname path)
(lambda (output-port)
(display content output-port))))
(define (compile-document compiler path)
(nml-doc-compile (nml-doc-parse path) compiler))
(define document (nml-doc-parse (nml-fs-path "document.nml")))
(define output (nml-fs-path "output.html"))
(write-file output (nml-doc-compile document "html"))
```
## The NML Object interface
NML offers it's own interface to allow scheme code to interact with nml data types.
Here's a list of syntax elements that have a scheme interface:
=Text=,
=StylePush=,
=StylePop=,
=Break=,
=Section=,
=ListBegin=,
=ListEnd=,
=ListEntry=,
=Ruler=,
=Figure=,
=Code=,
=Quote=,
=Reference=,
=Link=,
=Latex=,
=Raw=,
=RawInline=,
=ExternalRef=,
=Presentation=,
=Annotation=,
=CustomStylePush=,
=CustomStylePop=,
=CustomPresPush=,
=CustomPresPop=
All of these elements have a =make= method =nmlo-ELEMENT-make=
And also have setters and getters for each of their members: =nmlo-ELEMENT-FIELD-get= and =nmlo-ELEMENT-FIELD-set=.
# Compilers
## Text compiler
Text compiler is the compiler that compiles a parsed NML document to text, this is used for developping features and debugging.
## HTML compiler
HTML compiler is the compiler that compiles a parsed NML document to a HTML webpage.
**HTML Specific variables**
* =CSS= Location of a CSS file.
* =Title= Document's title
* =PageTitle= Web page title (default: =Title=)
* =Author= Document's author
* =Date= Date of document
* =TOC= Name of table of content (wille not appear unless set)
* =ExternalRef= Name of the external reference section
# Other resources
* [GNU Guile Reference Manual](https://www.gnu.org/software/guile/manual/)
* [Source code for this document](https://github.com/ef3d0c3e/NML/readme/readme.nml)
# Lua kernel
Simple kernel named `example`:
``Lua
@<example
function make_bold(text)
return "**" .. text .. "**"
end
>@
``
@<example
function make_bold(text)
return "**" .. text .. "**"
end
>@
Evaluating `!` from a kernel: `\%<![kernel] eval>\%`
* `\%<![example] make_bold("Hello, World!")>\%` → %<![example] make_bold("Hello, World!")>%
# Latex
# Support for inline maths:
* $\sum^{\infty}_{k=1} \frac{1}{k^2} = \frac{\pi^2}{6}$
* $n! = \int_0^\infty t^n e^{-t} \text{ d}t$