Update docs

This commit is contained in:
ef3d0c3e 2024-08-14 15:27:34 +02:00
parent b3b99c4069
commit fa68b68bf6
11 changed files with 164 additions and 77 deletions

View file

@ -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";
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

View file

@ -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

31
docs/references.nml Normal file
View file

@ -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

View file

@ -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

View file

@ -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,),
]
);
}
}

View file

@ -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

View file

@ -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!(""),

View file

@ -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;
);
}

View file

@ -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,

View file

@ -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,

View file

@ -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;