From 702830465ac87867fa4051a9be5036ef0b795c13 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Thu, 31 Aug 2023 23:02:14 -0400 Subject: Move man pages to their own directory --- doc/man/mandoc.css | 268 ++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/man/meson.build | 71 ++++++++++++++ doc/man/serdi.1 | 194 +++++++++++++++++++++++++++++++++++++ 3 files changed, 533 insertions(+) create mode 100644 doc/man/mandoc.css create mode 100644 doc/man/meson.build create mode 100644 doc/man/serdi.1 (limited to 'doc/man') diff --git a/doc/man/mandoc.css b/doc/man/mandoc.css new file mode 100644 index 00000000..9d255992 --- /dev/null +++ b/doc/man/mandoc.css @@ -0,0 +1,268 @@ +/* + Copyright 2021-2022 David Robillard + SPDX-License-Identifier: ISC +*/ + +/* Generic page style */ + +/* + Smaller sizes: 0.236em 0.271em 0.382em 0.438em 0.618em 0.708em + Larger sizes: 1.146em 1.618em 1.854em 2.618em 3em 4.236em +*/ + +html { + margin: 0 1.618em; + background: #FFF; + color: #000; +} + +body { + font-style: normal; + line-height: 1.618em; + margin: 0 auto auto; + padding: 0; + max-width: 60em; + font-family: "SF Pro Text", Verdana, "DejaVu Sans", sans-serif; + text-rendering: optimizelegibility; +} + +h1 { + font-family: Helvetica, Arial, "DejaVu Sans Condensed", Verdana, sans-serif; + font-size: 1.854em; + font-weight: 600; + line-height: 114.6%; + margin: 1.146em 0; +} + +a { + text-decoration: none; +} + +h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { + color: #222; +} + +a:hover { + text-decoration: underline; +} + +h1 a:link, h2 a:link, h3 a:link, h4 a:link, h5 a:link, h6 a:link { + color: #222; +} + +h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited { + color: #222; +} + +pre, tt, code { + overflow: auto; + font-family: "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", monospace, fixed; + hyphens: none; + white-space: nowrap; + + /* stylelint-disable property-no-vendor-prefix */ + -epub-hyphens: none; + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + /* stylelint-enable property-no-vendor-prefix */ +} + +ul, ol, dl { + margin: 0; + padding: 0; +} + +ul { + padding: 0; + hyphens: auto; +} + +dt { + font-weight: 600; + padding: 0.618em 0 0; +} + +dd { + margin: 0 0 0 2.618em; + hyphens: auto; +} + +dd > ul:only-child, dd > ol:only-child { + padding-left: 0; +} + +li { + margin-left: 2.618em; +} + +dt:empty { + margin: 0; + display: none; +} + +dd:empty { + margin: 0; + display: none; +} + +dt:blank { + margin: 0; + display: none; +} + +dd:blank { + margin: 0; + display: none; +} + +/* Media-specific style */ + +/* Color links on screens */ +@media screen { + a { + color: #546E00; + } +} + +@media print { + body { + color: #000; + } + + a, h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { + color: #000; + } + + a:link { + color: #000; + } + + a:visited { + color: #000; + } +} + +/* Mandoc specific style */ + +/* stylelint-disable selector-class-pattern */ + +table.head { + font-size: 0.708em; + margin: 0.438em 0 1.854em; + width: 100%; +} + +table.foot { + font-size: 0.708em; + margin: 2.618em 0 0.438em; + width: 100%; +} + +td.head-rtitle, td.foot-os { + text-align: right; +} + +td.head-vol { + text-align: center; +} + +div.Pp { + margin: 1ex 0; +} + +a.permalink { + color: #222; +} + +div.Nd, div.Bf, div.Op { + display: inline; +} + +span.Pa, span.Ad { + font-style: italic; +} + +span.Ms { + font-weight: bold; +} + +dl.Bl-diag > dt { + font-weight: bold; +} + +table.Nm tbody tr { + vertical-align: baseline; +} + +code.Nm, code.Fl, code.Cm, code.Ic, code.In, code.Fd, code.Fn, code.Cd { + font-weight: bold; + color: #444; +} + +code.Ev { + font-weight: bold; + color: #444; +} + +code.Li { + color: #333; +} + +var.Ar { + font-style: italic; +} + +/* stylelint-enable selector-class-pattern */ + +/* Dark mode */ +@media (prefers-color-scheme: dark) { + html { + background: #222; + color: #DDD; + } + + a { + color: #B4C342; + } + + a.permalink { + color: #DDD; + } + + h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { + color: #DDD; + } + + h1 a:link, h2 a:link, h3 a:link, h4 a:link, h5 a:link, h6 a:link { + color: #DDD; + } + + h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited { + color: #DDD; + } + + /* stylelint-disable selector-class-pattern */ + + code.Nm, code.Fl, code.Cm, code.Ic, code.In, code.Fd, code.Fn, code.Cd { + color: #AAA; + } + + code.Ev { + color: #AAA; + } + + code.Li { + color: #CCC; + } + + /* stylelint-enable selector-class-pattern */ +} + +/* Hard black for dark mode on mobile (since it's likely to be an OLED screen) */ +@media only screen and (hover: none) and (pointer: coarse) and (prefers-color-scheme: dark) { + html { + background: #000; + color: #CCC; + } +} diff --git a/doc/man/meson.build b/doc/man/meson.build new file mode 100644 index 00000000..323a8c4d --- /dev/null +++ b/doc/man/meson.build @@ -0,0 +1,71 @@ +# Copyright 2020-2023 David Robillard +# SPDX-License-Identifier: 0BSD OR ISC + +mandoc_css = files('mandoc.css') + +if get_option('lint') + stylelint = find_program('stylelint', required: get_option('tests')) + if stylelint.found() + test('stylelint', stylelint, args: [mandoc_css], suite: 'data') + endif +endif + +if not get_option('tools').disabled() + # Install tool man pages + if not get_option('man').disabled() + if not meson.is_subproject() + summary( + 'Man pages', + get_option('prefix') / get_option('mandir'), + section: 'Directories', + ) + endif + + install_man(files('serdi.1')) + endif + + # Build/install HTML man pages if mandoc is present + mandoc = find_program('mandoc', required: get_option('man_html')) + if mandoc.found() + configure_file( + copy: true, + input: mandoc_css, + output: 'mandoc.css', + install_dir: docdir / versioned_name / 'man', + ) + + mandoc_html_command = [ + mandoc, + '-Kutf-8', + '-Ostyle=mandoc.css,man=%N.html', + '-Thtml', + '-Wwarning,stop', + '@INPUT@', + ] + + page_names = [ + 'serdi', + ] + + html_mandir = docdir / versioned_name / 'man' + foreach name : page_names + custom_target( + name + '.html', + capture: true, + command: mandoc_html_command, + input: files(name + '.1'), + install: true, + install_dir: html_mandir, + output: name + '.html', + ) + endforeach + + if not meson.is_subproject() + summary( + 'HTML man pages', + get_option('prefix') / html_mandir, + section: 'Directories', + ) + endif + endif +endif diff --git a/doc/man/serdi.1 b/doc/man/serdi.1 new file mode 100644 index 00000000..f3e42756 --- /dev/null +++ b/doc/man/serdi.1 @@ -0,0 +1,194 @@ +.\" Copyright 2011-2022 David Robillard +.\" SPDX-License-Identifier: ISC +.Dd April 30, 2023 +.Dt SERDI 1 +.Os Serd 0.31.5 +.Sh NAME +.Nm serdi +.Nd read and write RDF syntax +.Sh SYNOPSIS +.Nm serdi +.Op Fl abefhlqv +.Op Fl c Ar prefix +.Op Fl i Ar syntax +.Op Fl o Ar syntax +.Op Fl p Ar prefix +.Op Fl r Ar root +.Op Fl s Ar string +.Ar input +.Op Ar base_uri +.Sh DESCRIPTION +.Nm +is a fast command-line utility for streaming and processing RDF data. +It reads an RDF document and writes the data to stdout, +possibly transformed and/or in a different syntax. +By default, +the input syntax is guessed from the file extension, +and output is written in NTriples or NQuads. +.Pp +.Nm +can be used to check for syntax errors, +convert from one syntax to another, +pretty-print documents, +or transform URIs and blank node IDs. +.Pp +The options are as follows: +.Bl -tag -width 3n +.It Fl a +Write ASCII output. +If this is enabled, all non-ASCII characters will be escaped, even if the output syntax allows them to be written in UTF-8. +.It Fl b +Bulk output writing. +If this is enabled, output will be written a page at a time, rather than a byte at a time. +.It Fl c Ar prefix +Chop +.Ar prefix +from matching blank node IDs. +This is typically used to revert the effects of +.Fl p . +For example, with +.Ar prefix +.Dq doc01 , +the blank node +.Li _:doc01b42 +will be emitted as +.Li _:b42 . +.It Fl e +Eat input one character at a time, rather than a page at a time which is the default. +This is useful when reading from a pipe since output will be generated immediately as input arrives, rather than waiting until an entire page of input has arrived. +With this option serdi uses one page less memory, but will likely be significantly slower. +.It Fl f +Fast and loose URI mode: +preserve full URIs (without qualifying or making relative), +and pass prefixed names through as-is. +.It Fl h +Print the command line options. +.It Fl i Ar syntax +Read input as +.Ar syntax . +Case is ignored, valid values are: +.Dq NQuads , +.Dq NTriples , +.Dq TriG , +.Dq Turtle . +.It Fl l +Lax (non-strict) parsing. +If this is enabled, recoverable syntax errors will print a warning, but parsing will proceed starting at the next statement if possible. +Note that data may be lost when using this option. +.It Fl o Ar syntax +Write output as +.Ar syntax . +Case is ignored, valid values are: +.Dq NQuads , +.Dq NTriples , +.Dq TriG , +.Dq Turtle . +.It Fl p Ar prefix +Add +.Ar prefix +to blank node IDs. +This can be used to avoid clashes between blank node IDs in input documents. +The effects can be reversed in a later run with +.Fl c . +For example, with +.Ar prefix +.Dq doc01 , +the blank node +.Li _:b42 +will be emitted as +.Li _:doc01b42 . +.It Fl q +Suppress all output except data. +.It Fl r Ar root +Keep relative URIs within a +.Ar root +URI. +This will avoid creating any relative URI references with leading path segments like +.Pa ../ +that enter a parent of +.Ar root . +.Pp +For example, +if +.Pa /home/you/file.ttl +is written to the file +.Pa /home/me/output.ttl +using the destination's base URI, +then it could be written as +.Li <../you/file.ttl> . +Setting +.Fl r Li file:///home/me/ +would prevent references from +.Dq escaping +like this, +so the above would instead be written as +.Li , +since it can't be expressed relative to the root URI. +.Pp +This is useful for keeping relative references within some directory. +.It Fl s Ar string +Parse +.Ar string +input instead of a file (terminates options). +.It Fl v +Display version information and exit. +.El +.Sh EXIT STATUS +.Nm +exits with a status of 0, or non-zero if an error occurred. +.Sh EXAMPLES +.Bl -tag -width 3n +.It Pretty-print a document: +.Nm Fl o +.Ar turtle +.Pa file.ttl +> +.Pa out.ttl +.It Print any errors: +.Nm Pa file.ttl +> +.Pa /dev/null +.El +.Sh SEE ALSO +.Bl -item -compact +.It +.Lk http://drobilla.net/software/serd/ +.It +.Lk http://gitlab.com/drobilla/serd/ +.El +.Sh STANDARDS +.Bl -item +.It +.Rs +.%A W3C +.%T RDF 1.1 NQuads +.%D February 2014 +.Re +.Lk https://www.w3.org/TR/n-quads/ +.It +.Rs +.%A W3C +.%D February 2014 +.%T RDF 1.1 NTriples +.Re +.Lk https://www.w3.org/TR/n-triples/ +.It +.Rs +.%A W3C +.%T RDF 1.1 TriG +.%D February 2014 +.Re +.Lk https://www.w3.org/TR/trig/ +.It +.Rs +.%A W3C +.%D February 2014 +.%T RDF 1.1 Turtle +.Re +.Lk https://www.w3.org/TR/turtle/ +.El +.Sh AUTHORS +.Nm +is a part of serd, by +.An David Robillard +.Mt d@drobilla.net . -- cgit v1.2.1