From fa68b68bf60cd554a8ace6136d68020ec177914d Mon Sep 17 00:00:00 2001 From: ef3d0c3e Date: Wed, 14 Aug 2024 15:27:34 +0200 Subject: [PATCH] Update docs --- docs/external/graphviz.nml | 59 +++++++++++++++++++++++++++---------- docs/external/latex.nml | 27 +++++++++++++++-- docs/references.nml | 31 +++++++++++++++++++ docs/sections.nml | 11 +++++++ src/compiler/navigation.rs | 27 ++++++----------- src/compiler/postprocess.rs | 4 +-- src/elements/media.rs | 10 ++++--- src/elements/reference.rs | 31 +++++-------------- src/elements/section.rs | 4 +-- src/elements/tex.rs | 16 +++++----- style.css | 21 +++++++++++-- 11 files changed, 164 insertions(+), 77 deletions(-) create mode 100644 docs/references.nml diff --git a/docs/external/graphviz.nml b/docs/external/graphviz.nml index 778f50d..1dec944 100644 --- a/docs/external/graphviz.nml +++ b/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 diff --git a/docs/external/latex.nml b/docs/external/latex.nml index a1e2e4d..e873aea 100644 --- a/docs/external/latex.nml +++ b/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 diff --git a/docs/references.nml b/docs/references.nml new file mode 100644 index 0000000..846288a --- /dev/null +++ b/docs/references.nml @@ -0,0 +1,31 @@ +@import template.nml +@nav.previous = Sections +%% + +#{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 diff --git a/docs/sections.nml b/docs/sections.nml index d12c188..a3a8717 100644 --- a/docs/sections.nml +++ b/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 diff --git a/src/compiler/navigation.rs b/src/compiler/navigation.rs index cc7d5ad..e6bba72 100644 --- a/src/compiler/navigation.rs +++ b/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,), + ] + ); } } diff --git a/src/compiler/postprocess.rs b/src/compiler/postprocess.rs index e4d3388..0f6b054 100644 --- a/src/compiler/postprocess.rs +++ b/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 diff --git a/src/elements/media.rs b/src/elements/media.rs index 2e632b4..b07b340 100644 --- a/src/elements/media.rs +++ b/src/elements/media.rs @@ -148,9 +148,7 @@ impl Element for Medium { result.push_str(format!(r#"
"#, self.refid(compiler, refcount)).as_str()); result += match self.media_type { MediaType::IMAGE => format!(r#""#, self.uri), - MediaType::VIDEO => format!( - r#""#, - self.uri + MediaType::VIDEO => format!(r#""#, self.uri ), MediaType::AUDIO => { format!(r#""#, 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#"{caption}"#, + "{caption}", + self.uri + )), + MediaType::VIDEO => Ok(format!( + "{caption}", self.uri )), _ => todo!(""), diff --git a/src/elements/reference.rs b/src/elements/reference.rs index e5ec436..69996df 100644 --- a/src/elements/reference.rs +++ b/src/elements/reference.rs @@ -53,7 +53,7 @@ impl Element for InternalReference { ) -> Result { 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; ); } diff --git a/src/elements/section.rs b/src/elements/section.rs index a213da1..11a78a4 100644 --- a/src/elements/section.rs +++ b/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)| { - let kind = match kind.as_str() { + |_, (title, depth, kind, reference): (String, usize, Option, Option)| { + 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, diff --git a/src/elements/tex.rs b/src/elements/tex.rs index a7e985a..596d273 100644 --- a/src/elements/tex.rs +++ b/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, Option)| { + |_, (kind, tex, env, caption): (String, String, Option, Option)| { 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, Option)| { + |_, (kind, tex, env, caption): (String, String, Option, Option)| { 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$ -%% -%% -%% +%% +%% +%% "# .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$ -%% -%% -%% +%% +%% +%% "# .to_string(), None, diff --git a/style.css b/style.css index 70e08dc..e0243d3 100644 --- a/style.css +++ b/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;