//! The manpages, rendered from the sources the docs render from: the clap
//! definitions, the option, environment and key registries, the format descriptors,
//! `examples.toml` and the query and format-spec references.
//!
//! The pages are rendered by `gen_docs write` and committed under
//! `crates/datui-cli/man/`; `the_generated_docs_are_current` fails while a committed
//! page differs. Committed, they need nothing at build time: the
//! references live outside this crate, which a build from crates.io could not read,
//! and every package, tarball and `datui man` takes the same files. The date is the
//! release's (`release-date.txt`, set by `scripts/bump_version.py`), never the build's,
//! so a page is the same however and whenever it is built.
mod plain;
pub mod roff;
use clap::CommandFactory;
use roff::{Headings, Markdown, arg, bold, example_block, inline, italic, line, literal, text};
use crate::settings::{self, DefaultValue, EnvGroup};
use crate::{exit, keys};
/// What a page renders from, beyond this crate: a repository file's text, by its path
/// from the root.
pub type Read<'a> = &'a dyn Fn(&str) -> String;
/// One manpage.
pub struct Page {
/// `datui-config`.
pub name: &'static str,
pub section: u8,
/// The committed page, as `datui man` prints it.
pub text: &'static str,
render: fn(&Page, Read) -> String,
}
macro_rules! page {
($name:literal, $section:literal, $render:expr) => {
Page {
name: $name,
section: $section,
text: include_str!(concat!("../../man/", $name, ".", $section)),
render: $render,
}
};
}
/// Every page, in the order `datui man --list` and the docs list them.
pub const PAGES: &[Page] = &[
page!("datui", 1, |p, read| render_datui(p, read)),
page!("datui-config", 1, |p, read| render_command(
p, read, "config"
)),
page!("datui-catalog", 1, |p, read| render_command(
p, read, "catalog"
)),
page!("datui-theme", 1, |p, read| render_command(p, read, "theme")),
page!("datui-cache", 1, |p, read| render_command(p, read, "cache")),
page!("datui-views", 1, |p, read| render_command(p, read, "views")),
page!("datui-formats", 1, |p, read| render_command(
p, read, "formats"
)),
page!("datui-completions", 1, |p, read| render_command(
p,
read,
"completions"
)),
page!("datui-man", 1, |p, read| render_command(p, read, "man")),
page!("datui-config", 5, |p, read| render_config_file(p, read)),
page!("datui-keys", 7, |p, read| render_keys(p, read)),
page!("datui-query", 7, |p, read| render_query(p, read)),
page!("datui-formats", 7, |p, read| render_formats(p, read)),
];
/// The date every page carries: the release's, from `release-date.txt`.
pub const RELEASE_DATE: &str = include_str!("../../release-date.txt");
const BUGS: &str = "https://github.com/derekwisong/datui/issues";
const DOCS: &str = "https://derekwisong.github.io/datui/";
impl Page {
/// `datui-config.5`: the file name, and how examples name the page.
pub fn file_name(&self) -> String {
format!("{}.{}", self.name, self.section)
}
/// `datui-config(5)`.
pub fn title(&self) -> String {
format!("{}({})", self.name, self.section)
}
/// Where the page is committed, from the repository's root.
pub fn path(&self) -> String {
format!("crates/datui-cli/man/{}", self.file_name())
}
/// The page as `gen_docs` renders it.
pub fn render(&self, read: Read) -> String {
roff::tidy(&(self.render)(self, read))
}
/// The committed page's text with a Windows checkout's line endings undone.
pub fn roff(&self) -> String {
self.text.replace("\r\n", "\n")
}
/// The page as plain text filled to `width` columns, for a system without `man`.
pub fn plain(&self, width: usize) -> String {
plain::render(&self.roff(), width)
}
/// The NAME line's description, as `whatis` and `datui man --list` show it.
pub fn summary(&self) -> String {
match (self.name, self.section) {
("datui", 1) => lower_first(
&crate::Args::command()
.get_about()
.map(|a| a.to_string())
.unwrap_or_default(),
),
("datui-config", 5) => "the datui configuration file".into(),
("datui-keys", 7) => "the keys of every datui screen".into(),
("datui-query", 7) => "the q syntax of the datui command line".into(),
("datui-formats", 7) => "the formats datui reads, and format specs".into(),
(name, _) => {
let command = name.trim_start_matches("datui-");
let about = subcommand(command)
.get_about()
.map(|a| a.to_string())
.unwrap_or_default();
// The first clause: the NAME line is one line.
let first = about.split([':', ';']).next().unwrap_or(&about);
lower_first(first.trim())
}
}
}
}
/// The page `query` names: `datui-config`, `config`, `config.5`, `keys`. A name that
/// two sections share (`config`) is the command's, as `man` picks section 1 first.
pub fn find(query: &str) -> Option<&'static Page> {
let query = query.trim();
let (name, section) = match query.rsplit_once('.') {
Some((name, s)) if s.parse::<u8>().is_ok() => (name, s.parse::<u8>().ok()),
_ => (query, None),
};
let name = name.strip_prefix("datui-").unwrap_or(name);
PAGES.iter().find(|p| {
let short = p.name.strip_prefix("datui-").unwrap_or(p.name);
(short == name || p.name == name) && section.is_none_or(|s| s == p.section)
})
}
fn lower_first(s: &str) -> String {
let mut chars = s.chars();
match chars.next() {
// An initialism (`SQL`) keeps its case.
Some(c) if chars.clone().next().is_some_and(|n| n.is_lowercase()) => {
c.to_lowercase().chain(chars).collect()
}
Some(c) => std::iter::once(c).chain(chars).collect(),
None => String::new(),
}
}
fn subcommand(name: &str) -> clap::Command {
let mut cmd = crate::Args::command();
cmd.build();
cmd.find_subcommand(name)
.unwrap_or_else(|| panic!("no subcommand {name}"))
.clone()
}
/// The manual a section belongs to, as `.TH` names it.
fn manual(section: u8) -> &'static str {
match section {
1 => "User Commands",
5 => "File Formats",
_ => "Miscellaneous",
}
}
/// `.TH` and NAME.
fn head(page: &Page) -> String {
let mut out = String::from(".\\\" Generated by gen_docs from crates/datui-cli. Do not edit.\n");
out.push_str(&format!(
".TH {} {} {} {} {}\n",
literal(&page.name.to_uppercase()),
page.section,
RELEASE_DATE.trim(),
arg(&format!("datui {}", env!("CARGO_PKG_VERSION"))),
arg(manual(page.section)),
));
// No hyphenation and a ragged right, through the registers groff's man macros
// reset each paragraph from: an identifier (`DATUI_GCP_PROJECT`, a dotted key)
// broken at a hyphen reads as another word.
out.push_str(".nr HY 0\n.ds AD l\n");
out.push_str(&format!(
".SH NAME\n{} \\- {}\n",
literal(page.name),
text(&page.summary())
));
out
}
/// A paragraph of Markdown.
fn para(out: &mut String, md: &str) {
out.push_str(".PP\n");
out.push_str(&line(inline(md)));
out.push('\n');
}
/// A tagged paragraph: the tag is roff already, the body Markdown.
fn item(out: &mut String, tag: &str, md: &str) {
out.push_str(".TP\n");
out.push_str(&line(tag.to_string()));
out.push('\n');
out.push_str(&line(inline(md)));
out.push('\n');
}
/// An option's tag: `-F, --format FMT`, `--infer-types[=COLS|off]`, `PATH...`.
fn option_tag(a: &clap::Arg) -> String {
let values: Vec<String> = a
.get_value_names()
.map(|names| names.iter().map(|n| n.to_string()).collect())
.unwrap_or_default();
if a.is_positional() {
let names = values
.iter()
.map(|n| italic(n))
.collect::<Vec<_>>()
.join(" ");
return if a.get_num_args().is_some_and(|n| n.max_values() > 1) {
format!("{names} ...")
} else {
names
};
}
let mut names = Vec::new();
if let Some(s) = a.get_short() {
names.push(bold(&format!("-{s}")));
}
if let Some(l) = a.get_long() {
names.push(bold(&format!("--{l}")));
}
let mut tag = names.join(", ");
if a.get_action().takes_values() && !values.is_empty() {
let value = values
.iter()
.map(|n| italic(n))
.collect::<Vec<_>>()
.join(" ");
if a.get_num_args().is_some_and(|n| n.min_values() == 0) {
tag.push_str(&format!("[={value}]"));
} else {
tag.push(' ');
tag.push_str(&value);
}
}
tag
}
fn help_of(a: &clap::Arg) -> String {
let mut help = a
.get_long_help()
.or(a.get_help())
.map(|h| h.to_string())
.unwrap_or_default();
let shown: Vec<String> = a
.get_possible_values()
.iter()
.filter(|v| !v.is_hide_set())
.map(|v| format!("`{}`", v.get_name()))
.collect();
if !shown.is_empty() && !a.is_hide_possible_values_set() && a.get_action().takes_values() {
help.push_str(&format!(". One of {}", shown.join(", ")));
}
if !help.is_empty() && !help.ends_with('.') {
help.push('.');
}
help
}
fn options(out: &mut String, args: &[&clap::Arg]) {
for a in args {
item(out, &option_tag(a), &help_of(a));
}
}
fn shown_args(cmd: &clap::Command) -> Vec<&clap::Arg> {
cmd.get_arguments()
.filter(|a| !a.is_hide_set())
.filter(|a| !matches!(a.get_id().as_str(), "help" | "version"))
.collect()
}
fn exit_status(out: &mut String, session: bool) {
out.push_str(".SH \"EXIT STATUS\"\n");
for s in exit::STATUSES.iter().filter(|s| session || !s.session_only) {
item(out, &bold(&s.code.to_string()), s.means);
}
}
fn environment(out: &mut String, names: &[&str]) {
out.push_str(".SH ENVIRONMENT\n");
for var in settings::ENVIRONMENT
.iter()
.filter(|v| names.is_empty() || v.names.iter().any(|n| names.contains(n)))
{
environment_entry(out, var);
}
}
fn environment_entry(out: &mut String, var: &settings::EnvVar) {
let tag = var
.names
.iter()
.map(|n| bold(n))
.collect::<Vec<_>>()
.join(", ");
item(out, &tag, &format!("{}.", var.doc));
}
/// Where the config and cache directories are, then the files in them.
fn files(out: &mut String, which: Files) {
out.push_str(".SH FILES\n");
para(
out,
"*CONFIG* is `$DATUI_CONFIG_DIR` when it is set, else `$XDG_CONFIG_HOME/datui` (`~/.config/datui`) on Linux, `~/Library/Application Support/datui` on macOS and `%APPDATA%\\datui` on Windows.",
);
if which.cache {
para(
out,
"*CACHE* is `$DATUI_CACHE_DIR` when it is set, else `$XDG_CACHE_HOME/datui` (`~/.cache/datui`) on Linux, `~/Library/Caches/datui` on macOS and `%LOCALAPPDATA%\\datui` on Windows.",
);
}
let config: &[(&str, &str)] = &[
(
"CONFIG/config.toml",
"The config file: see datui-config(5). `datui config path` prints the files read",
),
(
"CONFIG/catalog.toml",
"Your catalog, which Ctrl+D on the home screen adds to: see datui-catalog(1)",
),
(
"CONFIG/catalogs/",
"More catalogs, one *.toml each, named by its file; examples.toml replaces the bundled one",
),
("CONFIG/views/", "Saved views: see datui-views(1)"),
(
"CONFIG/formats/",
"Format specs and dictionaries, searched first: see datui-formats(7)",
),
];
let cache: &[(&str, &str)] = &[
(
"CACHE/recents_history.txt",
"The recent datasets the home screen lists. `datui cache clear --recents` forgets them",
),
("CACHE/*_history.txt", "The prompts' history"),
(
"CACHE/shapes/, CACHE/facts/, CACHE/cloud_listings/",
"What the home screen has measured of datasets and listed of cloud sources, so it can show rows, columns and sizes without reading them again",
),
(
"CACHE/datui.log",
"The log, unless `log.file` names another",
),
];
let mut entries: Vec<&(&str, &str)> = Vec::new();
if which.config {
entries.extend(config);
}
if which.cache {
entries.extend(cache);
}
for (path, what) in entries {
let tag = path
.split(", ")
.map(|p| {
let (dir, rest) = p.split_once('/').unwrap_or((p, ""));
format!("\\fI{}\\fR/{}", literal(dir), literal(rest))
})
.collect::<Vec<_>>()
.join(", ");
item(out, &tag, &format!("{what}."));
}
}
#[derive(Clone, Copy)]
struct Files {
config: bool,
cache: bool,
}
fn examples(out: &mut String, page: &Page) {
let examples = crate::examples_of(&page.file_name());
if examples.is_empty() {
return;
}
out.push_str(".SH EXAMPLES\n");
for example in examples {
para(out, &format!("{}.", example.description));
// Each file it reads under its name, then the command.
for file in &example.files {
out.push_str(&format!(".PP\n{}\n", line(bold(&file.name))));
example_block(out, &file.text);
}
example_block(out, &example.command);
}
}
fn see_also(out: &mut String, page: &Page, others: &[&str]) {
out.push_str(".SH \"SEE ALSO\"\n");
let mut refs: Vec<String> = PAGES
.iter()
.filter(|p| p.file_name() != page.file_name())
.filter(|p| {
page.name == "datui" || p.name == "datui" || others.contains(&p.file_name().as_str())
})
.map(|p| format!("{}({})", bold(p.name), p.section))
.collect();
let external: &[(&str, u8)] = match page.name {
"datui" => &[("jq", 1), ("less", 1), ("journalctl", 1), ("vd", 1)],
"datui-man" => &[("man", 1)],
_ => &[],
};
refs.extend(external.iter().map(|(n, s)| format!("{}({s})", bold(n))));
out.push_str(&line(refs.join(", ")));
out.push('\n');
para(out, &format!("The datui documentation: <{DOCS}>"));
}
/// BUGS, AUTHORS and COPYRIGHT, the year from the license.
fn tail(out: &mut String, read: Read) {
out.push_str(".SH BUGS\n");
para(out, &format!("Report bugs at <{BUGS}>."));
out.push_str(".SH AUTHORS\n");
para(out, "Derek Wisong and the datui contributors.");
let license = read("LICENSE");
let copyright = license
.lines()
.find(|l| l.starts_with("Copyright"))
.unwrap_or("Copyright (c) Derek Wisong");
out.push_str(".SH COPYRIGHT\n.PP\n");
out.push_str(&line(text(copyright).replace("(c)", "\\(co")));
out.push('\n');
para(out, "datui is free software under the MIT License.");
}
fn render_datui(page: &Page, read: Read) -> String {
let mut cmd = crate::Args::command();
cmd.build();
let mut out = head(page);
out.push_str(".SH SYNOPSIS\n.nf\n");
out.push_str(&format!(
"{} [{}]... [{}]...\n",
bold("datui"),
italic("OPTION"),
italic("PATH")
));
out.push_str(&format!(
"{} | {} [{}]... [{}]\n",
italic("command"),
bold("datui"),
italic("OPTION"),
bold("-")
));
out.push_str(&format!(
"{} {} [{}]...\n",
bold("datui"),
italic("COMMAND"),
italic("ARG")
));
out.push_str(".fi\n");
out.push_str(".SH DESCRIPTION\n");
for paragraph in read("crates/datui-cli/long_about.txt").split("\n\n") {
para(
&mut out,
¶graph.split_whitespace().collect::<Vec<_>>().join(" "),
);
}
para(
&mut out,
"Each *PATH* is a file, a directory, a glob, or an `http://`, `https://`, `s3://`, `gs://` or `az://` (`abfss://`) URL. Files of one shape are read as one table. `-` reads standard input, as does no *PATH* when data is piped in; with no *PATH* and nothing piped in, datui starts at its home screen.",
);
para(
&mut out,
"A file is scanned where it is wherever its format allows, and only the rows on screen are read; sorting, queries and analysis read what they need. datui-formats(7) says how each format is read. On any screen, `?` shows its keys; datui-keys(7) lists them all.",
);
out.push_str(".SH OPTIONS\n");
let mut groups: Vec<Option<String>> = vec![None];
for a in cmd.get_arguments() {
let heading = a.get_help_heading().map(str::to_string);
if !groups.contains(&heading) {
groups.push(heading);
}
}
for group in groups {
let args: Vec<&clap::Arg> = shown_args(&cmd)
.into_iter()
.filter(|a| a.get_help_heading().map(str::to_string) == group)
.collect();
if args.is_empty() {
continue;
}
out.push_str(&format!(
".SS {}\n",
arg(&text(group.as_deref().unwrap_or("Arguments")))
));
options(&mut out, &args);
}
out.push_str(".SS Help\n");
item(
&mut out,
&format!("{}, {}", bold("-h"), bold("--help")),
"Print help: a summary with `-h`, more with `--help`.",
);
item(
&mut out,
&format!("{}, {}", bold("-V"), bold("--version")),
"Print the version.",
);
out.push_str(".SH COMMANDS\n");
for sub in cmd.get_subcommands().filter(|c| c.get_name() != "help") {
let about = sub.get_about().map(|a| a.to_string()).unwrap_or_default();
item(
&mut out,
&bold(&format!("datui {}", sub.get_name())),
&format!("{about}. See datui-{}(1).", sub.get_name()),
);
}
exit_status(&mut out, true);
out.push_str(".SH ENVIRONMENT\n");
for group in [
EnvGroup::Datui,
EnvGroup::Terminal,
EnvGroup::Programs,
EnvGroup::Cloud,
] {
out.push_str(&format!(".SS {}\n", arg(&text(group.title()))));
if group == EnvGroup::Cloud {
para(
&mut out,
"Read as each provider's own tools read them; a variable set but empty counts as unset. `[cloud] env_files` can read them from `.env` files.",
);
}
for var in settings::ENVIRONMENT.iter().filter(|v| v.group == group) {
environment_entry(&mut out, var);
}
}
files(
&mut out,
Files {
config: true,
cache: true,
},
);
examples(&mut out, page);
see_also(&mut out, page, &[]);
tail(&mut out, read);
out
}
/// The subcommands' pages, git-style: `datui-config(1)` for `datui config`.
fn render_command(page: &Page, read: Read, name: &str) -> String {
let cmd = subcommand(name);
let mut out = head(page);
let actions: Vec<&clap::Command> = cmd
.get_subcommands()
.filter(|c| c.get_name() != "help")
.collect();
let synopsis = |words: &str, c: &clap::Command| -> String {
let mut s = bold(words);
for a in shown_args(c) {
if a.get_id() == "config" {
continue;
}
let tag = option_tag(a);
if a.is_positional() && a.is_required_set() {
s.push_str(&format!(" {tag}"));
} else {
s.push_str(&format!(" [{tag}]"));
}
}
s
};
out.push_str(".SH SYNOPSIS\n.nf\n");
if actions.is_empty() || !cmd.is_subcommand_required_set() {
out.push_str(&synopsis(&format!("datui {name}"), &cmd));
out.push('\n');
}
for action in &actions {
out.push_str(&synopsis(
&format!("datui {name} {}", action.get_name()),
action,
));
out.push('\n');
}
out.push_str(".fi\n");
out.push_str(".SH DESCRIPTION\n");
let about = cmd
.get_long_about()
.or(cmd.get_about())
.map(|a| a.to_string())
.unwrap_or_default();
para(&mut out, &format!("{about}."));
let extra = match name {
"config" => "The file's keys are in datui-config(5).",
"catalog" => {
"A catalog is one TOML file of named datasets, local or remote, that the home screen lists as a section under its label. *CONFIG*/catalog.toml is yours, and Ctrl+D on a home row adds to it; every *CONFIG*/catalogs/*.toml is a catalog, named by its file, and `catalogs` in the config lists files elsewhere; examples ships with datui, and a catalogs/examples.toml replaces it. A catalog's top level holds `label` and `description`; every other table is a dataset, keyed by a short id of lowercase letters, digits and `-`. A dataset's keys: `name` (its row), `path` or `url`, `auth` (`auto` or `anonymous`) or `connection` (a `[[cloud.connections]]` name), `description`, `publisher`, `license`, `homepage`, `documentation` (an https link), `size` (a web file's bytes, shown until measured), `columns.NAME = { description, unit, values = { CODE = \"meaning\" } }` and `bookmarks.\"Name\" = \"path/\"`. A long legend is a `[id.columns.NAME.values]` table, with the column's other keys written as dotted keys. `datui catalog show examples` prints a worked example."
}
"theme" => {
"A theme is a set of colors, one per slot. night-market (dark) and day-market (light) are built in; every *CONFIG*/themes/*.toml is a theme, named by its file. A theme file holds `theme.colors` slots, plus `extends` (the theme its unset slots come from; without it, the built-in for the mode it is used in) and `description`. `theme.dark` and `theme.light` in the config pick the theme for each mode, and `theme.colors` lies over whichever is in use. A file with a mistake is left out with a warning, and its mode uses the built-in."
}
"cache" => {
"The cache holds nothing datui cannot rebuild; clearing it loses the recents' order and the prompts' history."
}
"views" => {
"A view is saved from the views list (`v`) at the table, and applied with `--view NAME` or from that list."
}
"formats" => {
"Format specs are TOML files that describe a binary format, or a family of delimited text files; datui-formats(7) describes them. The search path is *CONFIG*/formats, then `$DATUI_FORMATS_PATH`, then `[formats] path` in the config."
}
"completions" => {
"The script completes datui's options, commands and their values. Print it into the directory your shell loads completions from."
}
"man" => {
"With no option, prints the page, or shows it with man(1) when standard output is a terminal; where man(1) is missing, as plain text through a pager: `$PAGER`, else less(1) or more(1). `--dir` writes every page, so `man datui` finds them; a package or the release archive installs them already. *PAGE* is a page's name with or without `datui-`, and `.5` or `.7` for the file and topic pages when a command shares the name."
}
_ => "",
};
if !extra.is_empty() {
para(&mut out, extra);
}
if !actions.is_empty() {
out.push_str(".SH COMMANDS\n");
for action in &actions {
let about = action
.get_about()
.map(|a| a.to_string())
.unwrap_or_default();
item(
&mut out,
&bold(&format!("datui {name} {}", action.get_name())),
&format!("{about}."),
);
let args: Vec<&clap::Arg> = shown_args(action)
.into_iter()
.filter(|a| a.get_id() != "config")
.collect();
if !args.is_empty() {
out.push_str(".RS\n");
options(&mut out, &args);
out.push_str(".RE\n");
}
}
}
out.push_str(".SH OPTIONS\n");
let own: Vec<&clap::Arg> = shown_args(&cmd)
.into_iter()
.filter(|a| a.get_id() != "config")
.collect();
options(&mut out, &own);
let global = crate::Args::command();
if let Some(config) = global.get_arguments().find(|a| a.get_id() == "config") {
options(&mut out, &[config]);
}
item(
&mut out,
&format!("{}, {}", bold("-h"), bold("--help")),
"Print help.",
);
exit_status(&mut out, false);
let (env, which, related): (&[&str], Option<Files>, &[&str]) = match name {
"config" => (
&["DATUI_CONFIG_DIR", "DATUI_LOG"],
Some(Files {
config: true,
cache: false,
}),
&["datui-config.5"],
),
"catalog" => (
&["DATUI_CONFIG_DIR"],
Some(Files {
config: true,
cache: false,
}),
&["datui-config.5"],
),
"theme" => (
&["DATUI_CONFIG_DIR"],
Some(Files {
config: true,
cache: false,
}),
&["datui-config.5"],
),
"cache" => (
&["DATUI_CACHE_DIR"],
Some(Files {
config: false,
cache: true,
}),
&[],
),
"views" => (
&["DATUI_CONFIG_DIR"],
Some(Files {
config: true,
cache: false,
}),
&[],
),
"formats" => (
&["DATUI_CONFIG_DIR", "DATUI_FORMATS_PATH"],
Some(Files {
config: true,
cache: false,
}),
&["datui-formats.7"],
),
_ => (&[], None, &[]),
};
if !env.is_empty() {
environment(&mut out, env);
}
if let Some(which) = which {
files(&mut out, which);
}
examples(&mut out, page);
see_also(&mut out, page, related);
tail(&mut out, read);
out
}
fn render_config_file(page: &Page, read: Read) -> String {
let mut out = head(page);
out.push_str(".SH SYNOPSIS\n.nf\n");
out.push_str(&format!("\\fICONFIG\\fR/{}\n", literal("config.toml")));
out.push_str(&format!(
"{} {} {}\n",
bold("datui"),
bold("-c"),
italic("KEY=VALUE")
));
out.push_str(".fi\n");
out.push_str(".SH DESCRIPTION\n");
para(
&mut out,
"datui's settings are TOML: a table per section, `[display]`, and a key per setting. A key is written `section.name` here and with `-c`.",
);
para(
&mut out,
"Values are taken, lowest first, from the defaults, the files listed in `import` (in order), the config file, `-c KEY=VALUE` (repeatable), and a key's own flag. `datui config init` writes the file with every key commented out at its default, `datui config path` prints the files read, and `datui config keys` lists every key with its value in effect and what set it. A key datui does not know, or a value a key does not take, is an error that names it.",
);
out.push_str(".SS Types\n");
for (kind, written) in settings::TYPES {
item(&mut out, &italic(kind), written);
}
item(&mut out, &italic("bool"), "`true` or `false`.");
item(&mut out, &italic("path"), "A path; `~` and `$VAR` expand.");
out.push_str(".SH SETTINGS\n");
for section in settings::SECTIONS {
let keys: Vec<&settings::Setting> = settings::in_section(section.name).collect();
if keys.is_empty() {
continue;
}
let title = if section.name.is_empty() {
"Top level".to_string()
} else {
format!("[{}]", section.name)
};
out.push_str(&format!(".SS {}\n", arg(&literal(&title))));
if !section.intro.is_empty() {
para(&mut out, section.intro);
}
for setting in keys {
let kind = setting.kind.describe().replace("\\|", "|");
let tag = format!("{} ({})", bold(setting.key), italic(&kind));
let mut body = setting.doc.to_string();
if !body.ends_with('.') {
body.push('.');
}
match setting.default {
DefaultValue::Value(v) => body.push_str(&format!(" Default: `{v}`.")),
DefaultValue::Unset(_) => body.push_str(" Unset by default."),
DefaultValue::Color { dark, light } => {
body.push_str(&format!(" Default: `{dark}` dark, `{light}` light."))
}
}
if let Some(flag) = setting.flag {
body.push_str(&format!(" Flag: `--{flag}`."));
}
// A doc's own mention of a flag or key reads as Markdown would show it.
item(&mut out, &tag, &body.replace('|', "\\|"));
}
}
environment(&mut out, &["DATUI_CONFIG_DIR", "DATUI_LOG"]);
files(
&mut out,
Files {
config: true,
cache: false,
},
);
examples(&mut out, page);
see_also(&mut out, page, &["datui-config.1"]);
tail(&mut out, read);
out
}
/// One group of keys: its name, then a tagged paragraph per key.
fn key_group(out: &mut String, name: Option<&str>, keys: &[keys::Key]) {
if let Some(name) = name {
out.push_str(".PP\n");
out.push_str(&line(format!("\\fI{}\\fR", text(name))));
out.push('\n');
}
for key in keys {
out.push_str(".TP\n");
out.push_str(&line(bold(key.keys)));
out.push('\n');
out.push_str(&line(text(key.long())));
out.push('\n');
}
}
fn render_keys(page: &Page, read: Read) -> String {
let mut out = head(page);
out.push_str(".SH DESCRIPTION\n");
para(
&mut out,
"`?` or `F1` on any screen shows that screen's keys, grouped by task: `/` narrows them to those whose text matches, and Enter closes the help and presses the key on the line. This page lists every screen's keys, with the longer descriptions.",
);
out.push_str(".SH KEYS\n");
out.push_str(&format!(".SS {}\n", arg(&text("Every screen"))));
key_group(&mut out, None, keys::GLOBAL.keys);
out.push_str(&format!(".SS {}\n", arg(&text("Help"))));
key_group(&mut out, None, keys::HELP.keys);
out.push_str(&format!(".SS {}\n", arg(&text("Question"))));
para(&mut out, "When datui asks before acting.");
key_group(&mut out, None, keys::QUESTION.keys);
for screen in keys::SCREENS {
out.push_str(&format!(".SS {}\n", arg(&text(screen.title))));
para(&mut out, screen.reached);
for group in screen.groups {
key_group(&mut out, Some(group.name), group.keys);
}
}
examples(&mut out, page);
see_also(&mut out, page, &[]);
tail(&mut out, read);
out
}
/// What a query example runs on: the datasets of `scripts/docs/doc_datasets.toml`.
fn datasets(read: Read) -> toml::Table {
read("scripts/docs/doc_datasets.toml")
.parse()
.expect("doc_datasets.toml is TOML")
}
fn render_query(page: &Page, read: Read) -> String {
let mut out = head(page);
out.push_str(".SH SYNOPSIS\n.nf\n");
out.push_str(&format!(
"{} [{}] [{} {}] [{} {}]\n",
bold("select"),
italic("columns"),
bold("by"),
italic("groups"),
bold("where"),
italic("conditions")
));
out.push_str(".fi\n");
out.push_str(".SH DESCRIPTION\n");
// The summary the command line's help shows.
out.push_str(".SS In brief\n");
for (example, meaning) in keys::Q_SUMMARY {
out.push_str(".TP\n");
out.push_str(&line(literal(example)));
out.push('\n');
out.push_str(&line(text(meaning)));
out.push('\n');
}
let doc = read("docs/reference/query-syntax.md");
let table = datasets(read);
let label = |name: &str| -> String { format!("On the {} dataset (see DATASETS):", bold(name)) };
let md = Markdown {
headings: Headings::Sections,
dataset_label: Some(&label),
};
out.push_str(&md.render(&doc));
// Every dataset an example names, and how to open it.
let used: Vec<String> = doc
.lines()
.filter_map(|l| l.trim().strip_prefix("```"))
.filter_map(|info| {
info.split(',')
.find_map(|a| a.trim().strip_prefix("dataset="))
})
.map(str::to_string)
.fold(Vec::new(), |mut v, n| {
if !v.contains(&n) {
v.push(n);
}
v
});
out.push_str(".SH DATASETS\n");
para(
&mut out,
"The examples run on the Example datasets that come with datui (on the home screen). Open one, press `/`, and type the query.",
);
for name in used {
let entry = table.get(&name).and_then(|e| e.as_table());
let open = entry
.and_then(|e| e.get("url").or_else(|| e.get("open")))
.and_then(|v| v.as_str())
.unwrap_or_default();
out.push_str(&format!(".TP\n{}\n", line(bold(&name))));
out.push_str(".EX\n");
out.push_str(&line(literal(&format!("datui {open}"))));
out.push_str("\n.EE\n");
}
examples(&mut out, page);
see_also(&mut out, page, &[]);
tail(&mut out, read);
out
}
fn render_formats(page: &Page, read: Read) -> String {
let mut out = head(page);
out.push_str(".SH DESCRIPTION\n");
para(&mut out, &crate::docgen::format_count_sentence());
let sections = Markdown {
headings: Headings::Sections,
dataset_label: None,
};
let inside = Markdown {
headings: Headings::Subsections,
dataset_label: None,
};
// The overview's count sentence is above already.
let index = read("docs/formats/index.md");
let index = match crate::docgen::splice("docs/formats/index.md", &index, "format-count", "") {
Ok(text) => text,
Err(_) => index,
};
out.push_str(§ions.render(&index));
out.push_str(".SH \"FORMAT SPECS\"\n");
out.push_str(&inside.render(&read("docs/formats/format-specs.md")));
out.push_str(".SH \"FORMAT SPEC REFERENCE\"\n");
out.push_str(&inside.render(&read("docs/reference/format-specs.md")));
examples(&mut out, page);
see_also(&mut out, page, &["datui-formats.1"]);
tail(&mut out, read);
out
}
/// `docs/reference/manual-pages.md`'s list: each page, linked to its HTML.
pub fn render_markdown_index() -> String {
let mut out = String::from("| Page | What it covers |\n|---|---|\n");
for page in PAGES {
out.push_str(&format!(
"| [{}](man/{}.html) | {} |\n",
page.title(),
page.file_name(),
page.summary()
));
}
out
}
#[cfg(test)]
mod tests;