From b252610fbda897d27a71ab5c3d4e99c0f96157a5 Mon Sep 17 00:00:00 2001 From: ef3d0c3e Date: Mon, 29 Jul 2024 21:28:06 +0200 Subject: [PATCH] Fixes & Doc --- docs/external/latex.nml | 96 ++++++++++++++++++++++++++++++++++++ docs/index.nml | 6 +++ docs/lua/lua.nml | 20 ++++++++ docs/styles/basic.nml | 31 ++++++++++++ docs/styles/user-defined.nml | 7 +++ docs/template.nml | 8 +++ src/compiler/navigation.rs | 2 - src/elements/code.rs | 2 +- src/elements/variable.rs | 4 +- src/main.rs | 33 +++++++------ 10 files changed, 188 insertions(+), 21 deletions(-) create mode 100644 docs/external/latex.nml create mode 100644 docs/index.nml create mode 100644 docs/lua/lua.nml create mode 100644 docs/styles/basic.nml create mode 100644 docs/styles/user-defined.nml create mode 100644 docs/template.nml diff --git a/docs/external/latex.nml b/docs/external/latex.nml new file mode 100644 index 0000000..a2cffe6 --- /dev/null +++ b/docs/external/latex.nml @@ -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... diff --git a/docs/index.nml b/docs/index.nml new file mode 100644 index 0000000..e316267 --- /dev/null +++ b/docs/index.nml @@ -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! diff --git a/docs/lua/lua.nml b/docs/lua/lua.nml new file mode 100644 index 0000000..e13eecc --- /dev/null +++ b/docs/lua/lua.nml @@ -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, %%`` + +## 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, %%`` → %% + * ``Lua, %%`` → %% diff --git a/docs/styles/basic.nml b/docs/styles/basic.nml new file mode 100644 index 0000000..6d11646 --- /dev/null +++ b/docs/styles/basic.nml @@ -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**` + diff --git a/docs/styles/user-defined.nml b/docs/styles/user-defined.nml new file mode 100644 index 0000000..7847a56 --- /dev/null +++ b/docs/styles/user-defined.nml @@ -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 diff --git a/docs/template.nml b/docs/template.nml new file mode 100644 index 0000000..5d9a977 --- /dev/null +++ b/docs/template.nml @@ -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} diff --git a/src/compiler/navigation.rs b/src/compiler/navigation.rs index 5c19316..395a73f 100644 --- a/src/compiler/navigation.rs +++ b/src/compiler/navigation.rs @@ -144,7 +144,5 @@ pub fn create_navigation(docs: &Vec) -> Result 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, Range)>> { let mut result = vec![]; diff --git a/src/main.rs b/src/main.rs index 6a7f824..eb7e1eb 100644 --- a/src/main.rs +++ b/src/main.rs @@ -91,6 +91,7 @@ fn process( target: Target, files: Vec, db_path: &Option, + force_rebuild: bool, debug_opts: &Vec, ) -> Result, 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(); }