From 6d1d8269caf974769b807033f46f661174eb9cdc Mon Sep 17 00:00:00 2001 From: ef3d0c3e Date: Sun, 3 Nov 2024 11:52:26 +0100 Subject: [PATCH] Docs --- docs/blocks/code.nml | 2 +- docs/comments.nml | 16 ++++++++++ docs/external/latex.nml | 2 +- docs/imports.nml | 17 +++++++++++ docs/index.nml | 4 --- docs/raw.nml | 40 +++++++++++++++++++++++++ docs/references.nml | 2 +- docs/sections.nml | 5 ++++ docs/start.nml | 58 +++++++++++++++++++++++++++++++++--- docs/styles/user-defined.nml | 2 +- docs/variables.nml | 44 +++++++++++++++++++++++++++ 11 files changed, 180 insertions(+), 12 deletions(-) create mode 100644 docs/comments.nml create mode 100644 docs/imports.nml delete mode 100644 docs/index.nml create mode 100644 docs/raw.nml create mode 100644 docs/variables.nml diff --git a/docs/blocks/code.nml b/docs/blocks/code.nml index f70e02d..e9f4985 100644 --- a/docs/blocks/code.nml +++ b/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`` diff --git a/docs/comments.nml b/docs/comments.nml new file mode 100644 index 0000000..68256fc --- /dev/null +++ b/docs/comments.nml @@ -0,0 +1,16 @@ +@import template.nml +@nav.previous = Imports +%% + +# 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 diff --git a/docs/external/latex.nml b/docs/external/latex.nml index e873aea..aca9790 100644 --- a/docs/external/latex.nml +++ b/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. diff --git a/docs/imports.nml b/docs/imports.nml new file mode 100644 index 0000000..5e416a1 --- /dev/null +++ b/docs/imports.nml @@ -0,0 +1,17 @@ +@import template.nml +@nav.previous = References +%% + +# Imports + +NML lets you import documents into the current document via the following syntax: + +``Plain Text, @import `` +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.`` diff --git a/docs/index.nml b/docs/index.nml deleted file mode 100644 index 1787221..0000000 --- a/docs/index.nml +++ /dev/null @@ -1,4 +0,0 @@ -@import template.nml -%% - -# Welcome to the NML documentation! diff --git a/docs/raw.nml b/docs/raw.nml new file mode 100644 index 0000000..1782e6d --- /dev/null +++ b/docs/raw.nml @@ -0,0 +1,40 @@ +@import template.nml +@nav.previous = References +%% + +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, {? ?} Some text {? ?}`` +#+LAYOUT_NEXT +{? ?} Some text {? ?} +#+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] ?}`` +#+LAYOUT_NEXT +{?[kind=block] ?} +#+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 diff --git a/docs/references.nml b/docs/references.nml index 98839fa..dfe838c 100644 --- a/docs/references.nml +++ b/docs/references.nml @@ -1,5 +1,5 @@ @import template.nml -@nav.previous = Sections +@nav.previous = Variables %% #{internal_references} Internal references diff --git a/docs/sections.nml b/docs/sections.nml index a3a8717..3fbb49a 100644 --- a/docs/sections.nml +++ b/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`` diff --git a/docs/start.nml b/docs/start.nml index bf54848..a37068b 100644 --- a/docs/start.nml +++ b/docs/start.nml @@ -1,14 +1,14 @@ @import template.nml -@nav.previous = Index %% -# 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 = {'nmlls'}, + filetypes = {'nml'}, + }) + end, +} +`` diff --git a/docs/styles/user-defined.nml b/docs/styles/user-defined.nml index 4e3dded..e3a4335 100644 --- a/docs/styles/user-defined.nml +++ b/docs/styles/user-defined.nml @@ -1,7 +1,7 @@ @import ../template.nml %% -# Defining a custom style +#{custom_style} Defining a custom style ```Lua function undercustom_start(color) nml.raw.push("inline", "") diff --git a/docs/variables.nml b/docs/variables.nml new file mode 100644 index 0000000..df22826 --- /dev/null +++ b/docs/variables.nml @@ -0,0 +1,44 @@ +@import template.nml +@nav.previous = Sections +%% + +# 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.