Fixes & Doc

This commit is contained in:
ef3d0c3e 2024-07-29 21:28:06 +02:00
parent a777e0ca8f
commit b252610fbd
10 changed files with 188 additions and 21 deletions

96
docs/external/latex.nml vendored Normal file
View file

@ -0,0 +1,96 @@
@import docs/template.nml
@compiler.output = latex.html
@nav.title = LaTeX
@nav.category = External Tools
@html.page_title = Documentation | LaTeX
@LaTeX = $|[kind=inline]\LaTeX|$
*Bring some %LaTeX% unto your document!*
# Inline Math
You can add inline math by enclosing %LaTeX% between two ``$``:
* ``$\lim_{n \to \infty} \Big(1 + \frac{1}{n}\Big)^n = e$`` → $\lim_{n \to \infty} \Big(1 + \frac{1}{n}\Big)^n = e$
* ``$\pi = \sqrt{\sum_{n=1}^\infty \frac{1}{n^2}}$`` → $\pi = \sqrt{\sum_{n=1}^\infty \frac{1}{n^2}}$
You can make the %LaTeX% non inline by specifying `kind=block` in it's property: ``$[kind=block] 1+1=2$`` → $[kind=block] 1+1=2$
*(notice how it's not inside a paragraph)*
# Non Math LaTeX
You can write %LaTeX% outside of %LaTeX%'s math environment, by enclosing your code between ``$|...|$``:
``LaTeX,
$|\begin{tikzpicture}
\begin{axis}
\addplot3[patch,patch refines=3,
shader=faceted interp,
patch type=biquadratic]
table[z expr=x^2-y^2]
{
x y
-2 -2
2 -2
2 2
-2 2
0 -2
2 0
0 2
-2 0
0 0
};
\end{axis}
\end{tikzpicture}|$
``
Gives the following:
$|\begin{tikzpicture}
\begin{axis}
\addplot3[patch,patch refines=3,
shader=faceted interp,
patch type=biquadratic]
table[z expr=x^2-y^2]
{
x y
-2 -2
2 -2
2 2
-2 2
0 -2
2 0
0 2
-2 0
0 0
};
\end{axis}
\end{tikzpicture}|$
# LaTeX environment
You can define multiple %LaTeX% environment, the default being `main`
* ``@tex.env.fontsize`` The fontsize (in pt) specified to `latex2svg` (default: `12`).
* ``@tex.env.preamble`` The preamble prepended to every %LaTeX% code.
* ``@tex.env.block_prepend`` Text to prepend to every non math %LaTeX% code.
* ``@tex.env.exec`` The `latex2svg` executable path, defaults to `latex2svg` (need to be in your `\$PATH`)
Replace ``env`` with the name of the custom environment you wish to define.
Here's a preamble to render %LaTeX% gray:
``
@tex.main.fontsize = 9
@tex.main.preamble = \usepackage{xcolor} \\
\usepgfplotslibrary{patchplots} \\
\definecolor{__color1}{HTML}{d5d5d5} \\
\everymath{\color{__color1}}
@tex.main.block_prepend = \color{__color1}
``
To set the environment you wish to use for a particular %LaTeX% element, set the `env` property:
* ``$[env=main] 1+1 = 2$`` → $[env=main] 1+1 = 2$
* ``$[env=other] 1+1 = 2$`` → $[env=other] 1+1 = 2$
# 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.
They are stored under the table named ``cached_tex``, if you modify the `env` all elements will be reprocessed which may take a while...

6
docs/index.nml Normal file
View file

@ -0,0 +1,6 @@
@import docs/template.nml
@compiler.output = index.html
@nav.title = Documentation
@html.page_title = Documentation | Index
# Welcome to the NML documentation!

20
docs/lua/lua.nml Normal file
View file

@ -0,0 +1,20 @@
@import docs/template.nml
@compiler.output = lua.html
@nav.title = Lua
@nav.category = Lua
@html.page_title = Documentation | Lua
# Running lua code
Running lua code is done using the following syntax:
``Lua, %<print("Hello World!")>%``
## Lua to text
To convert the return value of your lua code, append ``"`` at the start of your lua expression:
* ``Lua, %<"return "Hello World">%`` → %<"return "Hello World">%
* ``Lua, %<" "Hello, " .. "World">%`` → %<" "Hello, " .. "World">%
## Parse lua string
Additionnaly, you can output lua to be parsed by the document's parser. To do so, append ``!`` at the start of your lua expression:
* ``Lua, %<!"**" .. "Bold from lua?" .. "**">%`` → %<!"**" .. "Bold from lua?" .. "**">%
* ``Lua, %<!"[" .. "Link from Lua" .. "](#)">%`` → %<!"[" .. "Link from Lua" .. "](#)">%

31
docs/styles/basic.nml Normal file
View file

@ -0,0 +1,31 @@
@import docs/template.nml
@compiler.output = basic.html
@nav.title = Basic
@nav.category = Styles
@html.page_title = Documentation | Basic Styles
# Basic styles
## Bold
Enclose text between two ``**`` to render it **bold**!
* ``**Bold text**`` → **Bold text**
* ``**Bold [link](#)**`` → **Bold [link](#)**
## Italic
Enclose text between two ``*`` to render it *italic*!
* ``*Italic text*`` → *Italic text*
* ``**Bold + *Italic***`` → **Bold + *Italic***
## Underline
Enclose text between two ``__`` to render it __underlined__!
* ``__Underlined text__`` → __Underlined text__
* ``__Underline + *Italic*__`` → __Underline + *Italic*__
## Highlighted
Enclose text between two `` ` `` to render it `overlined`!
* `` `Highlighted text` `` → `Highlighted text`
* `` `Highlight + **Bold**` `` → `Highlight + **Bold**`

View file

@ -0,0 +1,7 @@
@import docs/template.nml
@compiler.output = user-defined.html
@nav.title = User-Defined
@nav.category = Styles
@html.page_title = Documentation | User-Defined Styles
# TODO

8
docs/template.nml Normal file
View file

@ -0,0 +1,8 @@
@'html.css = style.css
@tex.main.fontsize = 9
@tex.main.preamble = \usepackage{xcolor, tikz, pgfplots} \\
\usepgfplotslibrary{patchplots} \\
\definecolor{__color1}{HTML}{d5d5d5} \\
\everymath{\color{__color1}\displaystyle}
@tex.main.block_prepend = \color{__color1}

View file

@ -144,7 +144,5 @@ pub fn create_navigation(docs: &Vec<CompiledDocument>) -> Result<NavEntry, Strin
pent.entries.push((title.clone(), path.clone()))
}
println!("{nav:#?}");
Ok(nav)
}

View file

@ -321,7 +321,7 @@ impl CodeRule {
)
.unwrap(),
Regex::new(
r"``(?:\[((?:\\.|[^\[\]\\])*?)\])?(?:(.*?)(?:\n|,))?((?:\\(?:.|\n)|[^\\\\])*?)``",
r"``(?:\[((?:\\.|[^\\\\])*?)\])?(?:(.*?),)?((?:\\(?:.|\n)|[^\\\\])*?)``",
)
.unwrap(),
],

View file

@ -13,7 +13,7 @@ pub struct VariableRule {
impl VariableRule {
pub fn new() -> Self {
Self {
re: [Regex::new(r"(?:^|\n)@([^[:alpha:]])?(.*)=((?:\\\n|.)*)").unwrap()],
re: [Regex::new(r"(?:^|\n)@([^[:alpha:]])?(.*?)=((?:\\\n|.)*)").unwrap()],
kinds: vec![
("".into(), "Regular".into()),
("'".into(), "Path".into())
@ -89,8 +89,6 @@ impl RegexRule for VariableRule {
fn regexes(&self) -> &[Regex] { &self.re }
fn on_regex_match<'a>(&self, _: usize, parser: &dyn Parser, document: &'a dyn Document, token: Token, matches: regex::Captures) -> Vec<Report<'_, (Rc<dyn Source>, Range<usize>)>>
{
let mut result = vec![];

View file

@ -91,6 +91,7 @@ fn process(
target: Target,
files: Vec<String>,
db_path: &Option<String>,
force_rebuild: bool,
debug_opts: &Vec<String>,
) -> Result<Vec<CompiledDocument>, String> {
let mut compiled = vec![];
@ -127,15 +128,19 @@ fn process(
Ok(compiled)
};
let cdoc = match CompiledDocument::from_cache(&con, &file) {
Some(compiled) => {
if compiled.mtime < modified.duration_since(UNIX_EPOCH).unwrap().as_secs() {
parse_and_compile()?
} else {
compiled
let cdoc = if force_rebuild {
parse_and_compile()?
} else {
match CompiledDocument::from_cache(&con, &file) {
Some(compiled) => {
if compiled.mtime < modified.duration_since(UNIX_EPOCH).unwrap().as_secs() {
parse_and_compile()?
} else {
compiled
}
}
None => parse_and_compile()?,
}
None => parse_and_compile()?,
};
compiled.push(cdoc);
@ -152,6 +157,7 @@ fn main() -> ExitCode {
opts.optopt("i", "input", "Input path", "PATH");
opts.optopt("o", "output", "Output path", "PATH");
opts.optopt("d", "database", "Cache database location", "PATH");
opts.optflag("", "force-rebuild", "Force rebuilding of cached documents");
opts.optmulti("z", "debug", "Debug options", "OPTS");
opts.optflag("h", "help", "Print this help menu");
opts.optflag("v", "version", "Print program version and licenses");
@ -204,8 +210,9 @@ fn main() -> ExitCode {
}
}
let debug_opts = matches.opt_strs("z");
let db_path = matches.opt_str("d");
let force_rebuild = matches.opt_present("force-rebuild");
let debug_opts = matches.opt_strs("z");
let mut files = vec![];
if input_meta.is_dir() {
@ -257,7 +264,7 @@ fn main() -> ExitCode {
}
// Parse, compile using the cache
let compiled = match process(Target::HTML, files, &db_path, &debug_opts) {
let compiled = match process(Target::HTML, files, &db_path, force_rebuild, &debug_opts) {
Ok(compiled) => compiled,
Err(e) => {
eprintln!("{e}");
@ -283,7 +290,7 @@ fn main() -> ExitCode {
Some(path) => path.clone(),
None => {
eprintln!("Unable to get output file for `{}`", doc.input);
return ExitCode::FAILURE;
continue;
}
};
@ -292,11 +299,7 @@ fn main() -> ExitCode {
let file = std::fs::File::create(output.clone() + "/" + out_path.as_str()).unwrap();
let mut writer = BufWriter::new(file);
write!(
writer,
"{}{}{}{}",
doc.header, nav, doc.body, doc.footer
).unwrap();
write!(writer, "{}{}{}{}", doc.header, nav, doc.body, doc.footer).unwrap();
writer.flush().unwrap();
}