Docs

docs/blocks/code.nml

@@ -85,7 +85,7 @@ fn real_position(
 
 Code theme can be controlled by the variable ``code.theme``. The default value is ``base16-ocean.dark``.
 According to [syntect](https://docs.rs/syntect/latest/syntect/highlighting/struct.ThemeSet.html#method.load_defaults)'s
-documentation, the following themes are enabled:
+documentation, the following themes are available:
  * ``base16-ocean.dark``
  * ``base16-eighties.dark``
  * ``base16-mocha.dark``

docs/comments.nml

@@ -0,0 +1,16 @@
+@import template.nml
+@nav.previous = Imports
+%<make_doc({}, "Comments", "Comments")>%
+
+# Comments
+
+NML supports line comment with the following syntax: ``Plain Text, :: Comment``
+
+Comments will eat any preceding white space.
+
+**Example**
+#+LAYOUT_BEGIN Split
+``Markdown, **Bold Text** :: This is a comment``
+#+LAYOUT_NEXT
+**Bold Text** :: This is a comment
+#+LAYOUT_END

docs/external/latex.nml

@@ -101,7 +101,7 @@ To set the environment you wish to use for a particular %LaTeX% element, set the
  *- `block` (default for non math mode) display %LaTeX% on it's own line.
  * ``caption`` Caption for accessibility, defaults to `none`.
 
-# LaTeX cache
+#{tex_cache} LaTeX cache
 
 %LaTeX% elements that have been successfully rendered to **svg** are stored in the cache database, to avoid processing them a second time.
 Note that this cache is shared between documents, so you don't need to reprocess them if they share the same environment.

docs/imports.nml

@@ -0,0 +1,17 @@
+@import template.nml
+@nav.previous = References
+%<make_doc({}, "Imports", "Imports")>%
+
+# Imports
+
+NML lets you import documents into the current document via the following syntax:
+
+``Plain Text, @import <PATH.nml>``
+Note that this will import everything from the other document, such as content but also variables and references.
+
+# Scoped imports
+
+If you wish to import a document, while not overwriting current variables and references, use the following:
+
+``Plain Text, @import[as=util] lib.nml``
+With this syntax, any variable or reference imported will be prefixed with ``util.``

docs/index.nml

@@ -1,4 +0,0 @@
-@import template.nml
-%<make_doc({}, "Index", "Index")>%
-
-# Welcome to the NML documentation!

docs/raw.nml

@@ -0,0 +1,40 @@
+@import template.nml
+@nav.previous = References
+%<make_doc({}, "Raw", "Raw")>%
+
+Raws are elements to be rendered as-is by the compiler.
+
+# Inline raws
+
+Inline raws are meant to be used inside a paragraph and thus, don't break the paragraph.
+Here's the syntax for inline raws: ``Plain Text, {?[kind=inline] CONTENT ?}``.
+Here, ``CONTENT`` will added directly to the resulting document.
+
+**Example**
+#+LAYOUT_BEGIN Split
+``Plain Text, {? <a style="color:red"> ?} Some text {? </a> ?}``
+#+LAYOUT_NEXT
+{? <a style="color:red"> ?} Some text {? </a> ?}
+#+LAYOUT_END
+
+Raws are better paired with Lua, see &{#custom_style}[caption=Defining a custom style] for how to use them.
+
+# Block raws
+
+You can have raw elements take a full block to define additional capabilities.
+The syntax is similar to inline raws, except that ``kind=block`` is used instead.
+
+**Example**
+#+LAYOUT_BEGIN Centered
+#+LAYOUT_BEGIN Split
+``Plain Text, {?[kind=block] <img src="assets/duck.jpg" style="max-height:100%;max-width:100%;"> ?}``
+#+LAYOUT_NEXT
+{?[kind=block] <img src="assets/duck.jpg" style="max-height:100%;max-width:100%;"> ?}
+#+LAYOUT_END
+#+LAYOUT_END
+
+
+# Properties
+ * ``kind`` The element kind of the resulting raw, defaults to `inline`, allowed values:
+ *- ``inline``: Make the raw element inline
+ *- ``block``: Make the raw element a full block

docs/references.nml

@@ -1,5 +1,5 @@
 @import template.nml
-@nav.previous = Sections
+@nav.previous = Variables
 %<make_doc({}, "References", "References")>%
 
 #{internal_references} Internal references

docs/sections.nml

@@ -41,6 +41,11 @@ You can then create a clickable reference to this section: ``§{refname}`` or ``
 §{refname}[caption=Click me!] or §{first}[caption=First section]
 ``
 
+# Table of Content
+
+Section can be automatically exported to a table of content, such as shown at the top of this document.
+To create a table of content, simply add ``#+TABLE_OF_CONTENT`` somewhere in your document and it will be displayed there.
+
 # Section styling
 
 The styling for the section link is controlled by the style key ``style.section``

docs/start.nml

@@ -1,14 +1,14 @@
 @import template.nml
-@nav.previous = Index
 %<make_doc({}, "Getting Started", "Getting Started")>%
 
-# Building NML
+#{building_nml} Building NML
 
 You need at least the nightly version of rustc to compile NML.
 Instruction for your operating system can be found on [Rust's website](https://forge.rust-lang.org/infra/other-installation-methods.html).
 You'll also need liblua 5.4 installed. You can then move the `nml` executable in `target/release/nml` into your `\$PATH`
 
 ``cargo build --bin nml`` or for release mode: ``cargo build --release --bin nml``
+*(Note: The release build binary is much smaller than the debug build one)*
 
 # Building your first document
 
@@ -16,17 +16,67 @@ You'll also need liblua 5.4 installed. You can then move the `nml` executable in
 
 # Using the cache
 
-NML relies on sqlite to keep a cache of precompiled elements that take a long time to process (e.g $|[kind=inline] \LaTeX|$).
+NML relies on sqlite to keep a cache of pre-compiled elements that take a long time to process (e.g $|[kind=inline] \LaTeX|$).
 To enable caching, use option `-d` with a path: ``-d cache.db``. You can reuse the same cache for multiple documents and benefit from cached elements.
 Note that in directory-processing mode, a cache is required so that only modified ``.nml`` files get reprocessed.
 
+**Elements that will use the cache:**
+ * All $|[kind=inline] \LaTeX|$ elements
+ (*NOTE: Upon modification of the $|[kind=inline] \LaTeX|$ environment, they will be reprocessed, see &{#tex_cache}[caption=TeX Cache] for more information*)
+ * All Graphviz elements
+ * All code blocks
+
 # Directory-Processing mode
 
 To use directory-processing mode, you need to pass an input directory and an output directory. Directory-processing mode requires that you use a database, so that it knows which documents have already been compiled. If the output directory doesn't exist, it will be automatically created.
 
 Compiling the docs: 
-``Plain Text,
+``Plain Text
 nml -i docs -o docs_out -d cache.db
 ``
 
 If you modify an ``Plain Text,@import``ed file, you will need to use the ``--force-rebuild`` option, as NML currently doesn't track which files are imported by other files.
+
+# Building the Language Server
+
+NML comes with it's own language server, ready to be used in any LSP-compatible text editor, such as NeoVim.
+
+Build it by using the following command: ``cargo build --bin nmlls`` or for release mode: ``cargo build --release --bin nmlls``
+*(Note: The release build binary is much smaller than the debug build one)*
+
+You should move the language server somewhere in your ``$PATH``.
+
+##* Integrating the LSP
+
+Below is a list of integration steps the language server in various editors.
+
+###* NeoVim
+
+The first step is to add the `.nml` extension to NeoVim, so it is recognized:
+``Lua
+vim.filetype.add({
+	pattern = {
+		['.*%.nml'] = 'nml',
+	},
+})
+``
+
+Then you need to register the language server in NeoVim. I recommend the ``lsp-zero`` plugin for that purpose:
+``Lua
+{
+	"VonHeikemen/lsp-zero.nvim",
+	config = function()
+		local lsp_zero = require('lsp-zero')
+
+		lsp_zero.on_attach(function(client, bufnr)
+			lsp_zero.default_keymaps({buffer = bufnr})
+		end)
+
+		lsp_zero.new_client({
+			name = 'nmlls',
+			cmd = {'<PATH TO BINARY IF NOT IN $PATH/>nmlls'},
+			filetypes = {'nml'},
+		})
+	end,
+}
+``

docs/styles/user-defined.nml

@@ -1,7 +1,7 @@
 @import ../template.nml
 %<make_doc({"Styles"}, "User-Defined", "User-Defined Styles")>%
 
-# Defining a custom style
+#{custom_style} Defining a custom style
 ```Lua
 function undercustom_start(color)
 	nml.raw.push("inline", "<span style=\"border-bottom: 1px dashed " .. color .. "\">")

docs/variables.nml

@@ -0,0 +1,44 @@
+@import template.nml
+@nav.previous = Sections
+%<make_doc({}, "Variables", "Variables")>%
+
+# Variable definition
+
+In NML you can defines variables and call them later.
+
+Currently, two types of variables are supported:
+ * **Text variables**: Just simple text
+ * **Path variables**: Path aware variables, that will display an error if the path doesn't exist or is not accessible
+
+To define a variable use the following syntax:
+``Markdown
+@var = value
+:: Text variable
+@'my_file = ./pic.png
+:: Path variable
+``
+
+Variable names cannot contain `\%` or `=`. However variables values can span across multiple lines:
+``Markdown
+@var = A\
+B
+:: var == "AB"
+@var = A\\
+B
+:: var == "A\nB"
+``
+
+Using a single `\\`'s will ignore the following newline, using two `\\\\`'s will keep the newline.
+
+# Variable substitution
+
+Once variables have been defined, you can call them to be expanded to their content:
+
+``Markdown
+@var = Hello, World!
+:: Definition
+%var%
+:: Substitution
+``
+
+Expanded variables will be processed by the parser to display their content, as if you had written the variable's value directly.