Update docs

docs/external/graphviz.nml

@@ -8,28 +8,50 @@
 digraph {
 	bgcolor=transparent;
 	graph[fontcolor=darkgray];
-	node[fontcolor=darkgray];
-	edge[fontcolor=darkgray, color=gray90];
+	node[shape=box,fontcolor=darkgray];
+	edge[fontcolor=darkgray, color=gray];
+
+	filelist [color=orange, label="File List"];
+	doclist [color=orange, label="Document List"];
 
-	filelist [shape=box, color=orange, label="File List"];
-	doclist [shape=box, color=orange, label="Document List"];
 	iscached [shape=diamond, color=red, label="Cached?"];
-	parse [shape=box, color=white, label=Parse];
-	compile [shape=box,color=white, label=Compile];
-	cache [shape=box, color=orange, label=Cache];
+	parse [color=white, label=Parse];
+	compile [color=white, label=Compile];
+	cache [color=orange, label=Cache];
 
 	filelist -> iscached;
-	iscached -> cache[dir=both];
-	iscached -> doclist[label="Yes"];
+	iscached -> cache[dir=both,color=lightblue,style=dashed];
+	iscached -> doclist[label="Yes",color=lightblue,style=dashed];
+
+	iscached -> parse[label="No",color=lightblue,style=dashed];
+	subgraph cluster_0 {
+		style=dotted;
+		color=white;
+		label = "Processing";
+		labeljust="l";
+
+		parse -> compile;
+	}
 
-	iscached -> parse[label="No"];
-	parse -> compile;
-	compile -> cache[label=""];
 	compile -> doclist[label=""];
 
+
 	buildnav [color=white, label="Build Navigation"];
-	doclist -> buildnav;
-	output [color=white, label="Output"];
+	xref [color=white, label="Resolve Cross-References"];
+	
+	doclist -> xref;
+	doclist -> buildnav[label="Cached",color=lightblue,style=dashed];
+	
+	subgraph cluster_1 {
+		style=dotted;
+		color=white;
+		label = "Post-Processing";
+		labeljust="l";
+
+		xref -> buildnav;
+	}
+	xref -> cache[color=lightblue,style=dashed];
+	output [color=orange, label="Output"];
 	buildnav -> output;
 }
 [/graph]
@@ -43,7 +65,7 @@ Graphs blocks are delimited by `` [graph]...[/graph]``
 
 # Properties
  * ``layout`` The layout engine, defaults to `dot`
-	see [Graphviz's documentation](https://graphviz.org/docs/layouts/), allowed values:
+	see [Graphviz's documentation](https://graphviz.org/docs/layouts/). Allowed values:
  *- [`dot`](https://graphviz.org/docs/layouts/dot/)
  *- [`neato`](https://graphviz.org/docs/layouts/neato/)
  *- [`fdp`](https://graphviz.org/docs/layouts/fdp/)
@@ -313,3 +335,10 @@ digraph UML_Class_diagram {
 
 Graphviz graphs that have been rendered to **svg** are stored in the cache database, under table ``cached_dot``.
 Unless you modify the graph or it's properties, it won't be rendered again, instead it will be sourced from the database.
+
+# Bindigs
+
+ * ``Lua, nml.graphviz.push(layout, width, dot)``
+ ** ``layout`` *(string)* the layout engine
+ ** ``width`` *(string)* the width property (empty string for default)
+ ** ``dot`` *(string)* the graphviz code

docs/external/latex.nml

@@ -3,7 +3,14 @@
 
 @LaTeX = $|[kind=inline, caption=LaTeX]\LaTeX|$
 
+#+LAYOUT_BEGIN Centered
 *Bring some %LaTeX% unto your document!*
+#+LAYOUT_END
+
+# Requirements
+
+In order to use LaTeX processing, you need to have a %LaTeX% distribution installed. We recommend the [TeX Live](https://en.wikipedia.org/wiki/TeX_Live) distribution.
+You'll also need to install the [latex2svg](https://github.com/ef3d0c3e/nml/blob/master/third/latex2svg) python script provided with NML. You'll have to follow the installation instructions from the [original latex2svg repository](https://github.com/Moonbase59/latex2svg). If you don't want to add the script to your `\$PATH`, you can set the executable path in the §{tex_env}[caption=LaTeX environment].
 
 # Inline Math
 
@@ -64,7 +71,7 @@ $|\begin{tikzpicture}
 \end{tikzpicture}|$
 #+LAYOUT_END
 
-# LaTeX environment
+#{tex_env} LaTeX environment
 
 You can define multiple %LaTeX% environment, the default being `main`
  * ``@tex.env.fontsize`` The fontsize (in pt) specified to `latex2svg` (default: `12`).
@@ -98,4 +105,20 @@ To set the environment you wish to use for a particular %LaTeX% element, set the
 
 %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...
+They are stored under the table named ``Plain Text,cached_tex``, if you modify the `env` all elements will be reprocessed which may take a while...
+
+# Bindings
+
+ * ``Lua, nml.tex.push_math(kind, tex [, env [, caption]])``
+ inserts a math mode %LaTeX% element.
+ ** ``kind`` *(string)* the element kind (inline or block)
+ ** ``tex`` *(string)* the %LaTeX% code
+ ** ``env`` *(string)* the %LaTeX% environment (defaults to `main`)
+ ** ``caption`` *(string)* the accessibility caption
+
+ * ``Lua, nml.tex.push(kind, tex [, env [, caption]])``
+ inserts a non-math %LaTeX% element.
+ ** ``kind`` *(string)* the element kind (inline or block)
+ ** ``tex`` *(string)* the %LaTeX% code
+ ** ``env`` *(string)* the %LaTeX% environment (defaults to `main`)
+ ** ``caption`` *(string)* the accessibility caption

docs/references.nml

@@ -0,0 +1,31 @@
+@import template.nml
+@nav.previous = Sections
+%<make_doc({}, "References", "References")>%
+
+#{internal_references} Internal references
+
+Internal references allow you to create references to elements defined within the current document.
+
+Reference the the current section: ``§{internal_reference}`` → §{internal_references}
+
+## Media references
+![flower](assets/flower.webm)[caption = Flower]
+
+When you reference a medium from the current document, the reference can be hovered to show the referenced medium: §{flower}.
+
+# External references
+
+You can reference elements from other documents by adding the document's name before the reference name (separated by a ``#``).
+The document name refers to the output file (as defined by the variable `compiler.output`) excluding the extension.
+
+ * ``§{doc#ref}``: Finds reference named `ref` in document named `doc`.
+ * ``§{#ref}``: Finds reference named `ref` in all documents.
+ Note that this will fail if there are multiple documents defining reference `ref`.
+
+For instance:
+ * ``§{LaTeX#tex_env}[caption=LaTeX environment]`` → §{LaTeX#tex_env}[caption=LaTeX environment]
+ * ``§{#tex_env}[caption=LaTeX environment]`` → §{#tex_env}[caption=LaTeX environment]
+
+# Properties
+
+ * ``caption`` The display caption for the reference

docs/sections.nml

@@ -54,3 +54,14 @@ The styling for the section link is controlled by the style key ``style.section`
 	"link": ["", "🔗", " "]
 }
 ```
+
+# Bindings
+
+ * ``Lua, nml.section.push(title, depth, [, kind [, reference]])``
+ ** ``title`` *(string)* the section display title
+ ** ``depth`` *(number)* the section depth
+ ** ``kind`` *(string)* the section kind
+ **- `\*` for unnumbered
+ **- `+` for outside of the table of content
+ **- `\*+` or `+\*` for both
+ ** ``reference`` *(string)* the section reference name

src/compiler/navigation.rs

@@ -223,7 +223,7 @@ mod tests {
 
 	use crate::compiler::process::process_from_memory;
 
-use super::*;
+	use super::*;
 
 	#[test]
 	fn sort() {
@@ -278,22 +278,13 @@ use super::*;
 		.unwrap();
 
 		let nav = create_navigation(&result).unwrap();
-		assert_eq!(nav.children.get("First").unwrap().entries, vec![
-			(
-				"A".to_string(),
-				"1.html".to_string(),
-				None,
-			),
-			(
-				"B".to_string(),
-				"2.html".to_string(),
-				None,
-			),
-			(
-				"C".to_string(),
-				"0.html".to_string(),
-				None,
-			),
-		]);
+		assert_eq!(
+			nav.children.get("First").unwrap().entries,
+			vec![
+				("A".to_string(), "1.html".to_string(), None,),
+				("B".to_string(), "2.html".to_string(), None,),
+				("C".to_string(), "0.html".to_string(), None,),
+			]
+		);
 	}
 }

src/compiler/postprocess.rs

@@ -5,10 +5,10 @@ use crate::document::document::CrossReference;
 use super::compiler::CompiledDocument;
 use super::compiler::Target;
 
-/// Represents the list of tasks that have to be ran after the document has been compiled and the
+/// Represents the list of tasks that have to run after the document has been compiled and the
 /// compiled document list has been built. Every task is stored with a raw byte position in the
 /// compiled document's body. The position represents the original position and thus should be
-/// offset accordingly to other postprocessing tasks.
+/// offset accordingly to other post-processing tasks.
 pub struct PostProcess {
 	/// List of references to resolve i.e insert the resolved refname at a certain byte position
 	/// in the document's body

src/elements/media.rs

@@ -148,9 +148,7 @@ impl Element for Medium {
 				result.push_str(format!(r#"<div id="{}" class="medium"{width}>"#, self.refid(compiler, refcount)).as_str());
 				result += match self.media_type {
 					MediaType::IMAGE => format!(r#"<a href="{0}"><img src="{0}"></a>"#, self.uri),
-					MediaType::VIDEO => format!(
-						r#"<video controls{width}><source src="{0}"></video>"#,
-						self.uri
+					MediaType::VIDEO => format!(r#"<video controls{width}><source src="{0}"></video>"#, self.uri
 					),
 					MediaType::AUDIO => {
 						format!(r#"<audio controls src="{0}"{width}></audio>"#, self.uri)
@@ -205,7 +203,11 @@ impl ReferenceableElement for Medium {
 				// TODO Handle other kind of media
 				match self.media_type {
 					MediaType::IMAGE => Ok(format!(
-						r#"<a class="medium-ref">{caption}<img src="{}"></a>"#,
+						"<a class=\"medium-ref\" href=\"#medium-{refid}\">{caption}<img src=\"{}\"></a>",
+						self.uri
+					)),
+					MediaType::VIDEO => Ok(format!(
+						"<a class=\"medium-ref\" href=\"#medium-{refid}\">{caption}<video><source src=\"{0}\"></video></a>",
 						self.uri
 					)),
 					_ => todo!(""),

src/elements/reference.rs

@@ -53,7 +53,7 @@ impl Element for InternalReference {
 	) -> Result<String, String> {
 		match compiler.target() {
 			Target::HTML => {
-				let elemref = document.get_reference(self.refname.as_str()).unwrap();
+				let elemref = document.get_reference(self.refname.as_str()).ok_or(format!("Unable to find reference `{}` in current document", self.refname))?;
 				let elem = document.get_from_reference(&elemref).unwrap();
 
 				elem.compile_reference(
@@ -224,28 +224,7 @@ impl RegexRule for ReferenceRule {
 						);
 						return reports;
 					}
-					Ok(refname) => {
-						if document.get_reference(refname).is_none() {
-							reports.push(
-								Report::build(
-									ReportKind::Error,
-									token.source(),
-									refname_match.start(),
-								)
-								.with_message("Uknown Reference Refname")
-								.with_label(
-									Label::new((token.source().clone(), refname_match.range()))
-										.with_message(format!(
-											"Could not find element with reference: `{}`",
-											refname.fg(state.parser.colors().info)
-										)),
-								)
-								.finish(),
-							);
-							return reports;
-						}
-						(None, refname.to_string())
-					}
+					Ok(refname) => (None, refname.to_string())
 				}
 			}
 		} else {
@@ -325,6 +304,9 @@ mod tests {
 
 §{ref}[caption=Section]
 §{ref}[caption=Another]
+§{ref2}[caption=Before]
+
+#{ref2} Another section
 "#
 			.to_string(),
 			None,
@@ -337,7 +319,10 @@ mod tests {
 			Paragraph {
 				InternalReference { refname == "ref", caption == Some("Section".to_string()) };
 				InternalReference { refname == "ref", caption == Some("Another".to_string()) };
+				InternalReference { refname == "ref2", caption == Some("Before".to_string()) };
 			};
+			Paragraph;
+			Section;
 		);
 	}
 

src/elements/section.rs

@@ -330,8 +330,8 @@ impl RegexRule for SectionRule {
 		bindings.push((
 			"push".to_string(),
 			lua.create_function(
-				|_, (title, depth, kind, reference): (String, usize, String, Option<String>)| {
-					let kind = match kind.as_str() {
+				|_, (title, depth, kind, reference): (String, usize, Option<String>, Option<String>)| {
+					let kind = match kind.as_ref().map(|s| s.as_str()).unwrap_or("") {
 						"*+" | "+*" => section_kind::NO_NUMBER | section_kind::NO_TOC,
 						"*" => section_kind::NO_NUMBER,
 						"+" => section_kind::NO_TOC,

src/elements/tex.rs

@@ -442,7 +442,7 @@ impl RegexRule for TexRule {
 		bindings.push((
 			"push_math".to_string(),
 			lua.create_function(
-				|_, (env, kind, tex, caption): (Option<String>, String, String, Option<String>)| {
+				|_, (kind, tex, env, caption): (String, String, Option<String>, Option<String>)| {
 					let mut result = Ok(());
 					CTX.with_borrow(|ctx| {
 						ctx.as_ref().map(|ctx| {
@@ -484,7 +484,7 @@ impl RegexRule for TexRule {
 		bindings.push((
 			"push".to_string(),
 			lua.create_function(
-				|_, (env, kind, tex, caption): (Option<String>, String, String, Option<String>)| {
+				|_, (kind, tex, env, caption): (String, String, Option<String>, Option<String>)| {
 					let mut result = Ok(());
 					CTX.with_borrow(|ctx| {
 						ctx.as_ref().map(|ctx| {
@@ -545,9 +545,9 @@ mod tests {
 $[kind=block, caption=Some\, text\\] 1+1=2	$
 $|[env=another] Non Math \LaTeX |$
 $[kind=block,env=another] e^{i\pi}=-1$
-%<nml.tex.push_math(nil, "block", "1+1=2", "Some, text\\")>%
-%<nml.tex.push("another", "block", "Non Math \\LaTeX", nil)>%
-%<nml.tex.push_math("another", "block", "e^{i\\pi}=-1", nil)>%
+%<nml.tex.push_math("block", "1+1=2", nil, "Some, text\\")>%
+%<nml.tex.push("block", "Non Math \\LaTeX", "another", nil)>%
+%<nml.tex.push_math("block", "e^{i\\pi}=-1", "another", nil)>%
 			"#
 			.to_string(),
 			None,
@@ -573,9 +573,9 @@ $[kind=block,env=another] e^{i\pi}=-1$
 $[ caption=Some\, text\\] 1+1=2	$
 $|[env=another, kind=inline  ,   caption = Enclosed \].  ] Non Math \LaTeX|$
 $[env=another] e^{i\pi}=-1$
-%<nml.tex.push_math("main", "inline", "1+1=2", "Some, text\\")>%
-%<nml.tex.push("another", "inline", "Non Math \\LaTeX", "Enclosed ].")>%
-%<nml.tex.push_math("another", "inline", "e^{i\\pi}=-1", nil)>%
+%<nml.tex.push_math("inline", "1+1=2", "main", "Some, text\\")>%
+%<nml.tex.push("inline", "Non Math \\LaTeX", "another", "Enclosed ].")>%
+%<nml.tex.push_math("inline", "e^{i\\pi}=-1", "another", nil)>%
 			"#
 			.to_string(),
 			None,

style.css

@@ -201,7 +201,7 @@ div.code-block-content .code-block-line {
 	margin-right: .5em;
 }
 
-.medium img {
+.medium img, video, audio {
 	max-width: 100%;
 }
 
@@ -227,6 +227,7 @@ a.medium-ref {
 
 	font-weight: bold;
 	color: #d367c1;
+	text-decoration: none;
 }
 
 a.medium-ref:hover {
@@ -238,9 +239,23 @@ a.medium-ref img {
 	margin: 1.3em 0 0 0;
 }
 
+a.medium-ref video {
+	display: none;
+	margin: 1.3em 0 0 0;
+}
+
 a:hover.medium-ref img {
-	max-width: 50%;
-	margin: auto;
+	max-width: 25%;
+	left: 37.5%;
+	display: inline-block;
+	position: absolute;
+
+	box-shadow: 0px 0px 6px 2px rgba(0, 0, 0, 0.75);
+}
+
+a:hover.medium-ref video {
+	max-width: 25%;
+	left: 37.5%;
 	display: inline-block;
 	position: absolute;