чување 4871c6c1d27b606f21154021dbbcfb513c58954c
родитељ 4c19b005d3985c09c42fe10f8ea5810a3b66795e
Аутор: Страхиња Радић <contact@strahinja.org>
Датум: Mon, 6 May 2024 17:12:21 +0200
slweb.1.in: Syntax fixes; add DIAGNOSTICS and EXIT STATUS
Signed-off-by: Страхиња Радић <contact@strahinja.org>
Diffstat:
| M | slweb.1.in | | | 221 | ++++++++++++++++++++++++++++++++++++++++++++++++++----------------------------- |
измењених датотека: 1, додавања: 140(+), брисања: 81(-)
diff --git a/slweb.1.in b/slweb.1.in
@@ -34,7 +34,7 @@ and
.Ql {incdir} )
and favicons.
Defaults to the current directory
-.Pf "(" Do "." Dc Ns
+.Pf "(" Dq "." Ns
).
.It Fl h | Fl \-help
Print the usage information screen.
@@ -65,7 +65,7 @@ Text inside
will be put inside
.Ql <code></code> .
Text surrounded by triple backticks
-.Pf ( Ql ``` )
+.Pf "(" Ql "```" )
on the lines by themselves will be put inside
.Ql <pre></pre> .
Any
@@ -110,7 +110,8 @@ of the
should be avoided.
.
.It
-.Sy "Break marks" .
+.Tg Break_marks
+.Sy Break marks .
To address combinations of lists and
.Dq raw
tags, which are problematic to mix together,
@@ -186,12 +187,14 @@ produces:
</dd></dl>
.Ed
.It
-.Sy "Footnotes (regular and inline)" .
+.Sy Footnotes (regular and inline) .
Two-part regular footnotes can be added in a manner similar to links (see
-.Sx Links Ns ).
+.Sx Links Ns
+).
Inline footnotes are also supported.
.Bl -dash -width 1m
.It
+.Tg Regular_footnotes
.Sy Regular footnotes
have two mandatory parts: first, the footnote mark is represented by
.Ql [^ Ns Ar footnoteid Ns \[rB] ,
@@ -224,6 +227,7 @@ gives (some lines are wrapped for this manual):
With a footnote!
.Ed
.It
+.Tg Inline_footnotes
.Sy Inline footnotes
can be added by using the construct
.Ql ^[ Ns Ar footnotetext Ns \[rB] .
@@ -251,7 +255,8 @@ id by setting the YAML variable
to
.Dq 1
(see
-.Sx add\-footnote\-div Ns ).
+.Sx add-footnote-div Ns
+).
.Pp
Inline and regular footnotes can be used at the same time, but they don't share
the numbering.
@@ -279,7 +284,8 @@ with
.Ql ?\&
set to the number representing its position within the list of all headings.
.It
-.Sy "Horizontal rules" .
+.Tg Horizontal_rules
+.Sy Horizontal rules .
Three dashes at the start of the line will produce a
.Ql <hr>
in the output.
@@ -295,7 +301,8 @@ the asterisks.
.It
.Sy Images .
Similar to links (see
-.Sx Links Ns ),
+.Sx Links Ns
+),
images can be added by using:
.Bd -literal -offset Ds
@@ -326,7 +333,7 @@ As with links, a form similar to the
of links can also be used, using the image id instead of the direct URL.
.Pp
If the additional link or
-.Ql "<figure>" Ns
+.Ql <figure> Ns
.Pf / Ns Ql <figcaption>
tags are not desirable, they can be turned off by setting
.Va add-image-links
@@ -335,7 +342,8 @@ and
to
.Dq 0 .
.It
-.Sy "Keyboard tags" .
+.Tg Keyboard_tags
+.Sy Keyboard tags .
Text inside
.Ql ||double bars||\&
will be put inside
@@ -346,14 +354,15 @@ As with backticks, any
character will be converted to
.Ql <\& .
.It
-.Sy "Line breaks" .
+.Tg Line_breaks
+.Sy Line breaks .
Two spaces followed by a newline will become
.Ql <br> .
.It
.Sy Links .
.Bl -dash -width 1m
.It
-.Sy "Inline links" .
+.Sy Inline links .
The construct
.Ql [A link](https://example.com)
will be converted into
@@ -414,7 +423,7 @@ which will always output
.Ql <span>
tags.
.It
-.Sy "Regular links" .
+.Sy Regular links .
Everything said about inline links applies to regular links, with the exception
that instead of the parenthesized URL, link text inside brackets should be
followed by link id (different than the
@@ -440,10 +449,10 @@ This can help reduce the amount of code in the text of the page.
.It
.Sy Lists .
Lines starting with a dash
-.Pf "(" Ql - Ns
+.Pf "(" Ql "-" Ns
),
an asterisk
-.Pf "(" Ql * )
+.Pf "(" Ql "*" )
or lowercase
.Dq o ,
followed by a space, will start an unordered list (if used for the first time)
@@ -496,16 +505,18 @@ will produce:
Lists can't be nested, and the characters inside an existing list which would
otherwise start a list shall just be inserted as-is in the output.
.It
-.Sy "Non\-breaking hyphen" .
+.Tg Non-breaking_hyphen
+.Sy Non-breaking hyphen .
Tilde followed by a hyphen
-.Pf "(" Ql ~- )
+.Pf "(" Ql "~-" )
will insert
.Ql ‑\&
in the output.
.It
-.Sy "Non\-breaking space" .
+.Tg Non-breaking_space
+.Sy Non-breaking space .
Two consecutive tildes
-.Pf "(" Ql ~~ )
+.Pf "(" Ql "~~" )
will produce
.Ql \&
in the output.
@@ -515,17 +526,17 @@ Text surrounded by newlines will be prepended by
.Ql <p>
tag.
See
-.Sx "Known limitations" .
+.Sx Known limitations .
.It
.Sy Strikethrough .
Text surrounded by tildes
-.Pf "(" Ql ~ )
+.Pf "(" Ql "~" )
will be put inside
.Ql <s></s> .
.It
.Sy Tables .
Lines starting with vertical bars
-.Pf "(" Ql | )
+.Pf "(" Ql "|" )
will be transformed into HTML tables.
The first such line is treated as a header row, second as the alignment
specifier (currently ignored), and the rest regular rows.
@@ -551,6 +562,7 @@ will be transformed into:
</table>
.Ed
.It
+.Tg Partial_tables
.Sy Partial tables
are a modification of Markdown tables, allowing them to be combined with the TSV
or CSV directive.
@@ -575,18 +587,18 @@ The rest of the line following the third character in top, bottom and lines
separating header from body is ignored by the parser and is included in this
example only for aesthetic purposes.
See
-.Sx "TSV/CSV templating" .
+.Sx TSV/CSV templating .
.El
.
-.Ss "Math mode"
+.Ss Math mode
Math mode is supported through KaTeX.
With
.Nm katex
installed, anything between dollar signs
-.Pf "(" Ql $ )
+.Pf "(" Ql "$" )
will be transformed into MathML and HTML markup.
To generate display math, use double dollar signs
-.Pf "(" Ql $$ Ns
+.Pf "(" Ql "$$" Ns
).
The text between the dollar signs in both cases should be LaTeX source code, and
is passed to
@@ -598,11 +610,13 @@ or
.Va inline-stylesheet
YAML variables (see
.Sx stylesheet ,
-.Sx inline-stylesheet Ns ).
+.Sx inline-stylesheet Ns
+).
.
.Ss Directives
.Bl -bullet -width 1m
.It
+.Tg Brand_watermark
.Bf Sy
Brand
.Dq watermark Ns
@@ -618,13 +632,15 @@ text and a link to the
.Nm
home page.
.It
-.Sy "General tags" .
+.Tg General_tags
+.Sy General tags .
Directive
.Ql {sometag}{/sometag}
will be transformed into
.Ql <sometag></sometag> .
.It
-.Sy "Class attributes" .
+.Tg Class_attributes
+.Sy Class attributes .
Directive
.Ql {tag.myclass mysecondclass}{/tag}
will be transformed into
@@ -641,7 +657,8 @@ A variation of this is to use a special form
which will be transformed into
.Ql <div class="myclass"></div> .
.It
-.Sy "Id attributes" .
+.Tg Id_attributes
+.Sy Id attributes .
Directive
.Ql {tag#myid}{/tag}
will be transformed into
@@ -682,7 +699,8 @@ Macro definitions can't be nested nor can they contain macro calls, and doing so
will produce an error.
Tags won't be processed within the body of a macro.
.It
-.Sy "Previous Git commit information" .
+.Tg Previous_Git_commit_information
+.Sy Previous Git commit information .
Directive
.Ql {git\-log}
is converted into a div with the id
@@ -690,9 +708,12 @@ is converted into a div with the id
containing the information about the previous commit (as having information
about the current commit would be impossible).
.It
-.Sy "Subdirectory inclusion (blogging directive)" .
+.Tg Subdirectory_inclusion
+.Sy Subdirectory inclusion (blogging directive) .
The directive
-.Dl {incdir \(dq Ns Ar dirname Ns \(dq Ar num No = Ns Ar macroname No listonly}
+.Bd -literal -offset Ds
+.Pf { Ns Ic incdir \(dq Ns Ar dirname Ns \(dq Oo Ar num Oc Oo Cm = Ns Ar macroname Oc Oo Cm listonly Oc Ns }
+.Ed
.Pf "(" Ar num ,
.Ar macroname
and the literal
@@ -770,9 +791,8 @@ directive.
.Sx Includes
and
.Sx date ,
-.Sx ext\-in\-permalink ,
-.Sx permalink\-url ,
-.Sx samedir\-permalink
+.Sx ext-in-permalink ,
+.Sx permalink-url
variables.)
The output of each file will be surrounded by an
.Ql <article>
@@ -786,15 +806,15 @@ set to
only the text within the summary marks
.Pf "(" Ql /-
and
-.Ql -/ )
+.Ql "-/" )
will be output, and if the variable
-.Va incdir\-footer\-permalink\-text
+.Va incdir-footer-permalink-text
is also set,
.Ql <footer>
element with a permalink to the article will be added after it.
Example:
.Pp
-.Pf ( Pa posts/blog-post.slw )
+.Pf "(" Pa posts/blog-post.slw )
.Bd -literal -offset Ds
---
incdir-only-summary: 1
@@ -807,7 +827,7 @@ dog. The quick brown fox jumps over the lazy sleeping dog. The quick brown fox
jumps over the lazy sleeping dog.
.Ed
.Pp
-.Pf ( Pa blog-index.slw )
+.Pf "(" Pa blog-index.slw )
.Bd -literal -offset Ds
---
incdir-footer-permalink-text: Click here!
@@ -870,9 +890,12 @@ jumps over the lazy sleeping dog.
for
.Pa posts/blog-post.slw .
.It
-.Sy "TSV/CSV templating" .
+.Tg TSV/CSV_templating
+.Sy TSV/CSV templating .
Directive
-.Dl {tsv \(dq Ns Ar tsvfile Ns \(dq Ar iter Ns }{/tsv}
+.Bd -literal -offset Ds
+.Pf { Ns Ic tsv \(dq Ns Ar tsvfile Ns \(dq Oo Ar iter Oc Ns }{/ Ns Ic tsv Ns }
+.Ed
marks a template.
Whatever is between
.Ql {tsv}
@@ -892,20 +915,21 @@ of a register mark
.Ar n
is between 1 and 9, inclusive) with the corresponding TSV field of the read
line.
+.Pp
All of this applies to the similar
.Ql {csv}
directive for CSV files.
In the case of CSV files, they need to use semicolons
-.Pf "(" Ql ";" Ns
-) or commas
-.Pf "(" Ql "," Ns
-) as delimiters (or set
-.Va csv\-delimiter
+.Pf "(" Ql ";" )
+or commas
+.Pf "(" Ql "," )
+as delimiters (or set
+.Sx csv-delimiter
as a YAML variable in the calling
.Pa .slw
file) and double quotation marks
-.Pf "(" Ql "\(dq" Ns
-) as field boundaries.
+.Pf "(" Ql "\(dq" )
+as field boundaries.
First line in the TSV file is parsed as a header and associated with register
marks
.Ql $#1
@@ -992,7 +1016,7 @@ No newline is output following the number.
.Ss Special YAML variables
.Bl -bullet -width 1m
.It
-.Va add\-article\-header .
+.Va add-article-header .
If set to
.Dq 1 ,
title, date and header text at the beginning of the output body will be enclosed
@@ -1000,29 +1024,32 @@ in a
.Ql <header>
tag.
.It
-.Va add\-figcaption .
+.Va add-figcaption .
If set to
.Dq 0 ,
.Ql <figure>
and
.Ql <figcaption>
tags around images will not be added (otherwise they will by default, see
-.Sx Images Ns ).
+.Sx Images Ns
+).
.It
-.Va add\-footnote\-div .
+.Va add-footnote-div .
If set to
.Dq 1 ,
list of footnotes preceded by a horizontal rule will be surrounded with a div
having the id
.Dq footnotes
(see
-.Sx Footnotes Ns ).
+.Sx Footnotes Ns
+).
.It
-.Va add\-image\-links .
+.Va add-image-links .
If set to
.Dq 0 ,
links around images will not be added (otherwise they will by default, see
-.Sx Images Ns ).
+.Sx Images Ns
+).
.It
.Va author .
If set, the contents of this variable will be added to the start of the output
@@ -1038,7 +1065,7 @@ attribute for the
.Ql <link rel="canonical">
tag.
.It
-.Va csv\-delimiter .
+.Va csv-delimiter .
Changes the delimiter used for
.Pa .csv
file parsing.
@@ -1046,7 +1073,7 @@ By default, this will be a semicolon\
.Pf "(" Ns Ql ";" Ns
).
See
-.Sx "CSV templating" .
+.Sx TSV/CSV templating .
.It
.Va date .
If present, this variable, assumed to be in ISO\ 8601 UTC datetime format, will
@@ -1066,7 +1093,7 @@ and
with the argument
.Cm listonly Ns ).
.It
-.Va ext\-in\-permalink .
+.Va ext-in-permalink .
If set to
.Dq 0 ,
permalinks generated by the
@@ -1079,13 +1106,13 @@ For example, instead of
the resulting permalink will have
.Pa blog/2020/august .
.It
-.Va favicon\-url .
+.Va favicon-url .
If present, this URL will be used as a favicon URL instead of the default,
.Pa /favicon.ico .
.It
.Va feed ,
-.Va feed\-type ,
-.Va feed\-desc .
+.Va feed-type ,
+.Va feed-desc .
If all are present, contents of those variables will be added as
.Cm href ,
.Cm type
@@ -1096,14 +1123,14 @@ attributes (respectively) to the
tag in the page's
.Ql <head> .
.It
-.Va header\-text .
+.Va header-text .
The contents of this variable will be added to the start of the output body
(inside a
.Ql <header>
tag if it is set), preceeded by
.Ql <p> .
.It
-.Va image\-file\-prefix .
+.Va image-file-prefix .
If present, the value of
.Cm src
attribute will be appended to the contents of this variable, with path separator
@@ -1115,9 +1142,9 @@ Otherwise,
is appended to
.Dq .\& .
.It
-.Va incdir\-footer\-permalink\-text .
+.Va incdir-footer-permalink-text .
If set, and the variable
-.Va incdir\-only\-summary
+.Va incdir-only-summary
is set to
.Dq 1 ,
when the file where this variable is set is included by the
@@ -1130,7 +1157,7 @@ between the summary marks
and
.Ql -/ .
.It
-.Va incdir\-only\-summary .
+.Va incdir-only-summary .
If set to
.Dq 1 ,
when the file where this variable is set is included by the
@@ -1141,13 +1168,13 @@ and
.Ql -/
will be output.
.It
-.Va inline\-stylesheet .
+.Va inline-stylesheet .
The contents of this variable will be treated as a CSS file name to be included
inline in the header using the
.Ql <style>
tag.
You can add more than one
-.Va inline\-stylesheet
+.Va inline-stylesheet
declaration per
.Pa .slw
file.
@@ -1159,11 +1186,11 @@ attribute of the
.Ql <html>
tag.
.It
-.Va link\-prefix .
+.Va link-prefix .
This variable specifies the prefix which will be prepended to relative URLs in
links.
Final slash needs to be included if
-.Va link\-prefix
+.Va link-prefix
is a complete path.
.It
.Va meta .
@@ -1207,7 +1234,7 @@ file, a
.Pp
line will be added to the output.
.It
-.Va permalink\-url .
+.Va permalink-url .
If present, this URL will completely replace the link used in the
.Cm href
attribute of permalinks generated by the
@@ -1221,14 +1248,14 @@ provided to the
.Ic incdir
directive.
.It
-.Va site\-desc .
+.Va site-desc .
The contents of this variable will be inserted as the value of the
.Cm content
attribute of the
.Ql <meta name="description">
tag.
.It
-.Va site\-name .
+.Va site-name .
The contents of this variable will be inserted inside the
.Ql <title></title>
tags.
@@ -1248,19 +1275,19 @@ file.
If present, contents of this variable will be prepended to the body (inside a
.Ql <header>
tag if it is set) as a heading with the level determined by the
-.Va title\-heading\-level
+.Va title-heading-level
variable, defaulting to 2.
.Pf "(" Ns Ql title: Some title
becomes
.Ql <h2>Some title</h2> Ns
).
.It
-.Va title\-heading\-level .
+.Va title-heading-level .
See
.Sx title .
.El
.
-.Ss "Special macros"
+.Ss Special macros
.Bl -bullet -width 1m
.It
.Ic permalink .
@@ -1270,6 +1297,9 @@ the
directive, similar to the macro\-form of links.
.El
.
+.Sh EXIT STATUS
+.Ex -std
+.
.Sh EXAMPLES
Given the file
.Pa index.slw
@@ -1315,22 +1345,51 @@ contains:
</html>
.Ed
.
-.Sh "SEE ALSO"
+.Sh DIAGNOSTICS
+Error messages output by
+.Nm
+are in the format
+.Bd -ragged -offset Ds
+.Nm :
+.Ar filename : Ns Ar lineno : Ns Ar colno : Ar func : Ar msg
+.Ed
+.Pp
+where the
+.Ar filename
+is the name of the input file or
+.Ql (stdin)
+when no input file is specified,
+.Ar lineno
+and
+.Ar colno
+are the line and column numbers in the input file where the error occured.
+The argument
+.Ar func
+represents the name of the function where the error occured.
+.Pp
+When the error is caused by an error in the libc function which sets
+.Va errno ,
+.Nm
+calls
+.Xr perror 3
+prior to outputting an error message in the above format.
+.
+.Sh SEE ALSO
.Xr sed 1
.
.Sh AUTHORS
-.An "Strahinya Radich" Aq contact@strahinja.org ,
+.An Strahinya Radich Aq Mt contact@strahinja.org ,
2020\-2024
.
.Sh BUGS
Bugs can be reported using the ticket tracker at:
.Lk https://\:todo.sr.ht/\:~strahinja/\:slweb
.
-.Ss "Known limitations"
+.Ss Known limitations
The limitation of Markdown is that there is no clear way to determine where the
paragraph inside a tag should begin and end.
Before the addition of
-.Sx "Break marks"
+.Sx Break marks
and the change of behavior of
.Nm
to not output ending
