Update readme
This commit is contained in:
parent
5b39cfa789
commit
f89259eef5
1 changed files with 73 additions and 883 deletions
956
readme.nml
956
readme.nml
|
|
@ -1,896 +1,86 @@
|
||||||
#:Inc resources/template.nml
|
@html.page_title = NML -- Readme
|
||||||
#+Title NML -- The nice markup language!
|
@html.title = NML -- The nice markup languge!
|
||||||
#+TOC Table of content
|
@'html.css = style.css
|
||||||
|
|
||||||
%%(define (spoiler-text title content)
|
@tex.main.fontsize = 9
|
||||||
(string-append "{{{<details><summary>}}}" title "{{{</summary>}}}\n"
|
@tex.main.preamble = \usepackage{xcolor} \\
|
||||||
content
|
\definecolor{__color1}{HTML}{d5d5d5} \\
|
||||||
"{{{</details>}}}")
|
\everymath{\color{__color1}\displaystyle}
|
||||||
)
|
@tex.main.block_prepend = \color{__color1}
|
||||||
(define (make-anchor-link name)
|
|
||||||
(string-append "[" name "](#" (nml-html-get-anchor name) ")"))
|
|
||||||
%%
|
|
||||||
|
|
||||||
#+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.
|
```Plain Text, Example
|
||||||
|
First paragraph :: first '\n'
|
||||||
|
:: second '\n'
|
||||||
It currently is in an unstable stage. You should expect bugs and incomplete feature (CXXABI, NML Object, and Highlight caching).
|
Second paragraph
|
||||||
|
|
||||||
# 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)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 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
|
Unnumbered lists `\*`:
|
||||||
## Definitions
|
* A
|
||||||
|
* B
|
||||||
|
* C
|
||||||
|
|
||||||
NML allows defining internal variable that can be used inside a document, or by NML itself.
|
NML also supports list nesting of multiple kinds:
|
||||||
```c
|
* first
|
||||||
#+VariableName Value
|
* second
|
||||||
→ %VariableName% : "Value"
|
*- 2.1
|
||||||
|
*- 2.2
|
||||||
|
*-* even more nested
|
||||||
|
* third
|
||||||
|
|
||||||
#+SplitDefinition ValueLine1\
|
# Style
|
||||||
ValueLine2
|
|
||||||
→ %SplitDefinition% : "ValueLine1ValueLine2"
|
|
||||||
|
|
||||||
#+MultiLine First\\
|
NML supports markdown-based text styling:
|
||||||
Sec\
|
* \*\*bold\*\* -> **bold**
|
||||||
ond\\
|
* \*italic\* -> *italic*
|
||||||
Third
|
* \__underline\__ -> __underline__
|
||||||
→ %MultiLine% : "First\nSecond\nThird"
|
* \`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}}.
|
# Lua kernel
|
||||||
|
|
||||||
|
Simple kernel named `example`:
|
||||||
*Note*: If a variable is already defined, defining a new variable with the same name will overwrite the first variable
|
``Lua
|
||||||
```c
|
@<example
|
||||||
#+MyName Robert
|
function make_bold(text)
|
||||||
#+MyName John
|
return "**" .. text .. "**"
|
||||||
→ %MyName% : "John"```
|
end
|
||||||
|
>@
|
||||||
|
``
|
||||||
**Path-aware definitions**
|
@<example
|
||||||
|
function make_bold(text)
|
||||||
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.
|
return "**" .. text .. "**"
|
||||||
You can create path-aware definitions by adding a ='='s after the variable's name.
|
end
|
||||||
|
>@
|
||||||
```txt, Example use case
|
|
||||||
[File] My NML template file.nml
|
Evaluating `!` from a kernel: `\%<![kernel] eval>\%`
|
||||||
| #+Picture image.png
|
|
||||||
| #+PictureAware' image.png
|
* `\%<![example] make_bold("Hello, World!")>\%` → %<![example] make_bold("Hello, World!")>%
|
||||||
[File] image.png
|
|
||||||
[Folder] My project
|
# Latex
|
||||||
| [File] Project.nml
|
|
||||||
| | #:Inc ../My NML template file.nml
|
# Support for inline maths:
|
||||||
| |
|
* $\sum^{\infty}_{k=1} \frac{1}{k^2} = \frac{\pi^2}{6}$
|
||||||
| | %Picture% → image.png (wrong)
|
* $n! = \int_0^\infty t^n e^{-t} \text{ d}t$
|
||||||
| | %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:
|
|
||||||
 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)
|
|
||||||
 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)
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue