82 lines
3 KiB
Text
82 lines
3 KiB
Text
@import template.nml
|
|
%<make_doc({}, "Getting Started", "Getting Started")>%
|
|
|
|
#{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
|
|
|
|
* ``nml -i input.nml -o output.html``
|
|
|
|
# Using the cache
|
|
|
|
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
|
|
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,
|
|
}
|
|
``
|