чување eb90a58c1cb0d2b5c66d3a546c63aa93d69fe32c
родитељ 7eea073d2348ccc6aa89aa91e166381c4d25819d
Аутор: Страхиња Радић <contact@strahinja.org>
Датум: Wed, 1 May 2024 22:02:23 +0200
slweb.1.in: Convert to mdoc(7)
Signed-off-by: Страхиња Радић <contact@strahinja.org>
Diffstat:
| M | slweb.1.in | | | 2013 | +++++++++++++++++++++++++++++++++++++++++-------------------------------------- |
измењених датотека: 1, додавања: 1054(+), брисања: 959(-)
diff --git a/slweb.1.in b/slweb.1.in
@@ -1,470 +1,456 @@
-'\"
-.\" Manpage for slweb(1)
-.\" vim: set filetype=groff:
-.
-.mso an-ext.tmac
-.de CDS
-.EX
-.RS \\$1
-.sp 1
-..
-.de CDE
-.sp 1
-.RE
-.EE
-..
-.
-.TH SLWEB "1" "%DATE%" "slweb %VERSION%" "General Commands Manual"
-.SH NAME
-slweb \- Simple static website generator
-.
-.SH SYNOPSIS
-.
-.SY slweb
-.OP "\-h \fR|\fP \-\-help"
-.YS
-.
-.SY slweb
-.OP "\-v \fR|\fP \-\-version"
-.YS
-.
-.SY slweb
-.OP "\-b \fR|\fP \-\-body-only"
-.OP "\-d \fR|\fP \-\-basedir" directory
-.OP "\-p \fR|\fP \-\-global-link-prefix" URL
-.RI [ filename ]
-.YS
-.
-.SH COPYRIGHT
-slweb Copyright \(co 2020\-2024 Strahinya Radich.
-.br
-This program is licensed under GNU GPL v3 or later. See the file
-.I LICENSE
-in the slweb repository for details.
-.
-.SH DESCRIPTION
-.B slweb
-is a static website generator which aims at being simplistic. It transforms
-custom Markdown-like syntax into
-.SM HTML.
-.
-.SH OPTIONS
-.
-.TP
-.B \-b
-.TQ
-.B \-\-body\-only
-.br
-Only add the contents of the \fC<body>\fR tag, skipping \fC<html>\fR and
-\fC<head>\fR.
-.
-.TP
-.BI \-d " directory"
-.TQ
-.BI \-\-basedir " directory"
-.br
-Set the base directory for includes (\fC{include}\fR and \fC{incdir}\fR) and
-favicons. Defaults to the current directory (\[lq].\[rq]).
-.
-.TP
-.B \-h
-.TQ
-.B \-\-help
-.br
-Print this usage information screen.
-.
-.TP
-.BI \-p " URL"
-.TQ
-.BI \-\-global-link-prefix " URL"
-.br
-Set
-.I URL
+.\" This program is licensed under the terms of GNU GPL v3 or (at your option)
+.\" any later version. Copyright (C) 2020-2024 Страхиња Радић.
+.\" See the file LICENSE for exact copyright and license details.
+.Dd %DATE%
+.Dt SLWEB 1
+.Os
+.Sh NAME
+.Nm slweb
+.Nd Simple static website generator
+.Sh SYNOPSIS
+.Nm
+.Fl h | \-help | Fl V | \-full\-version | Fl v | \-version
+.Nm
+.Oo Fl b Oc Oo Fl d Ar directory Oc Oo Fl p Ar URL Oc
+.Op Ar filename
+.Nm
+.Oo Fl \-body\-only Oc Oo Fl \-basedir Ar directory Oc
+.Oo Fl \-global\-link\-prefix Ar URL Oc Op Ar filename
+.
+.Sh DESCRIPTION
+.Nm
+is a static website generator which aims at being simplistic.
+It transforms custom Markdown\-like syntax into HTML.
+.
+.Bl -tag -width Ds
+.It Fl b | Fl \-body\-only
+Only add the contents of the
+.Ql <body>
+tag, skipping
+.Ql <html>
+and
+.Ql <head> .
+.It Fl d Ar directory | Fl \-basedir Ar directory
+Set the base directory for includes
+.Pf "(" Ql {include}
+and
+.Ql {incdir} )
+and favicons.
+Defaults to the current directory
+.Pf "(" Do "." Dc Ns ).
+.It Fl h | Fl \-help
+Print the usage information screen.
+.It Fl p Ar URL | Fl \-global-link-prefix Ar URL
+Set
+.Ar URL
as a global prefix for relative links.
-..
-.TP
-.B \-v
-.TQ
-.B \-\-version
-.br
-Print program version and exit.
+.It Fl V | Fl \-full\-version
+Print full version (like
+.Fl v Ns ),
+followed by copyright notice, and exit.
+.It Fl v | Fl \-version
+Print program version and commit date, and exit.
+.El
.
-.SH REFERENCE
-.
-.LP
Files processed by
-.B slweb
-are using a minimal subset of Markdown with added directives.
-.
-.SS Supported Markdown features
-.
-.IP \[bu] 4
-.BR Backticks .
-Text inside \fC`backticks`\fR will be put inside \fC<code></code>\fR. Text
-surrounded by triple backticks (\fC```\fR) on the lines by themselves will be
-put inside \fC<pre></pre>\fR. Any \[lq]less-than\[rq] characters inside backticks
-will be converted to \fC<\fR and \[lq]ampersand\[rq] characters to
-\fC&\fR. Any text following the first triple backticks
-until the end of the line will be ignored. This is to account for language
-highlighting specification, which isn't yet supported.
-.
-.IP \[bu]
-.BR Blockquotes .
-Starting the line with \fC>\fR will surround it with a \fC<blockquote>\fR tag.
+.Nm
+are using a minimal subset of Markdown with added directives.
+.
+.Ss Supported Markdown features
+.
+.Bl -bullet -width 1m
+.It
+.Sy Backticks .
+Text inside
+.Ql `backticks`
+will be put inside
+.Ql <code></code> .
+Text surrounded by triple backticks
+.Pf ( Ql ``` )
+on the lines by themselves will be put inside
+.Ql <pre></pre> .
+Any
+.Dq less\-than
+characters inside backticks will be converted to
+.Ql <\[u003b]
+and
+.Dq ampersand
+characters to
+.Ql &\[u003b] .
+Any text following the first triple backticks until the end of the line will be
+ignored.
+This is to account for language highlighting specification, which isn't yet
+supported.
+.
+.It
+.Sy Blockquotes .
+Starting the line with
+.Ql >
+will surround it with a
+.Ql <blockquote>
+tag.
Multiple lines are supported.
.
-.IP \[bu]
-.BR Bold/italic .
-Text inside \fC*asterisks*\fR or \fC_underlines_\fR will be put inside
-\fC<em></em>\fR. Text inside \fC**double asterisks**\fR or \fC__double
-underlines__\fR will be put inside \fC<strong></strong>\fR. \fC***More than
-two*** of the ___same symbol___\fR should be avoided.
-.
-.IP \[bu]
-.BR "Break marks" .
-To address combinations of lists and \[lq]raw\[rq] tags, which are problematic
-to mix together,
-.B slweb
-supports explicitly marking a raw tag with a \[lq]break mark\[rq].
+.It
+.Sy Bold/italic .
+Text inside
+.Ql *asterisks*
+or
+.Ql _underlines_
+will be put inside
+.Ql <em></em> .
+Text inside
+.Ql **double asterisks**
+or
+.Ql __double underlines__
+will be put inside
+.Ql <strong></strong> .
+.Ql ***More than two***
+of the
+.Ql ___same symbol___
+should be avoided.
+.
+.It
+.Sy "Break marks" .
+To address combinations of lists and
+.Dq raw
+tags, which are problematic to mix together,
+.Nm
+supports explicitly marking a raw tag with a
+.Dq break mark .
This currently means that when such a tag is introduced, any running list item
and list will be closed prior to outputting the custom tag.
Tags with break marks are introduced by prepending the exclamation mark to the
tag name.
For example, without a break mark, the input:
-.
-.CDS 8
+.Bd -literal -offset Ds
- Some list
{break-here}
-.CDE
-.
-.IP
+.Ed
+.Pp
produces the following output:
-.
-.CDS 8
+.Bd -literal -offset Ds
<ul><li><p>Some list
-<break-here></p></li></ul>
-.CDE
-.
-.IP
+<break-here></li></ul>
+.Ed
+.Pp
When changed to:
-.
-.CDS 8
+.Bd -literal -offset Ds
- Some list
{!break-here}
-.CDE
-.
-.IP
-.B slweb
+.Ed
+.Pp
+.Nm
will output:
-.
-.CDS 8
+.Bd -literal -offset Ds
<ul><li><p>Some list
-</p></li></ul>
+</li></ul>
<break-here>
-.CDE
-.
-.IP
+.Ed
+.Pp
Same for end tags:
-.
-.CDS 8
+.Bd -literal -offset Ds
{dl}{dt}{p}Introduction{/dt}
{dd}
- One
- Two
{/dd}{/dl}
-.CDE
-.
-.IP
+.Ed
+.Pp
produces:
-.
-.CDS 8
+.Bd -literal -offset Ds
<dl><dt><p>Introduction</dt>
<dd>
<ul><li><p>One
-</p></li>
+</li>
<li><p>Two
-</dd></dl></p></li></ul>
-.CDE
-.
-.IP
+</dd></dl></li></ul>
+.Ed
+.Pp
while
-.
-.CDS 8
+.Bd -literal -offset Ds
{dl}{dt}{p}Introduction{/dt}
{dd}
- One
- Two
{/!dd}{/dl}
-.CDE
-.
-.IP
+.Ed
+.Pp
produces:
-.
-.CDS 8
+.Bd -literal -offset Ds
<dl><dt><p>Introduction</dt>
<dd>
<ul><li><p>One
-</p></li>
+</li>
<li><p>Two
-</p></li></ul>
+</li></ul>
</dd></dl>
-.CDE
-.
-.IP \[bu]
-.BR "Footnotes (regular and inline)" .
+.Ed
+.It
+.Sy "Footnotes (regular and inline)" .
Two-part regular footnotes can be added in a manner similar to links (see
-.BR Links ).
+.Sx Links Ns ).
Inline footnotes are also supported.
-.
-.RS
-.IP \- 4
-.B Regular footnotes
+.Bl -dash -width 1m
+.It
+.Sy Regular footnotes
have two mandatory parts: first, the footnote mark is represented by
-\fC[^\f[CI]footnoteid\f[CR]]\fR, where
-.I footnoteid
-is the footnote identifier. Second, the text of the footnote is represented by
-\fC[^\f[CI]footnoteid\f[CR]]: \f[CI]sometext\fR, with
-.I sometext
-being the text of the footnote. Footnote text construct needs to begin at the
-start of a line, and it is the most practical to have it placed near the bottom
-of the file, similar to normal links.
-.
-.IP ""
+.Ql [^ Ns Ar footnoteid Ns \[rB] Ns ,
+where
+.Ar footnoteid
+is the footnote identifier.
+Second, the text of the footnote is represented by
+.Ql [^ Ns Ar footnoteid Ns \[rB] : Ar sometext ,
+with
+.Ar sometext
+being the text of the footnote.
+Footnote text construct needs to begin at the start of a line, and it is the
+most practical to have it placed near the bottom of the file, similar to normal
+links.
+.Pp
Combined, the input:
-.CDS 8
+.Bd -literal -offset Ds
This is a text[^first].
[^first]: With a footnote!
-.CDE
-.
-.IP "" 4
+.Ed
+.Pp
gives (some lines are wrapped for this manual):
-.
-.CDS 8
+.Bd -literal -offset Ds
<p>This is a text<a href="#footnote-1" id="footnote-text-1">
-<sup>1</sup></a>.</p>
+<sup>1</sup></a>.
<hr>
-<p id="footnote-1"><a href="#footnote-text-1">1.</a>
-With a footnote!</p>
-.CDE
-.
-.IP \- 4
-.B Inline footnotes
-can be added by using the construct \fC^[footnotetext]\fR. For example, input
-.
-.CDS 8
+<p id="footnote-1"><a href="#footnote-text-1">1.</a>
+With a footnote!
+.Ed
+.It
+.Sy Inline footnotes
+can be added by using the construct
+.Ql ^[ Ns Ar footnotetext Ns \[rB] .
+For example, input
+.Bd -literal -offset Ds
Inline footnote^[Footnote text] in a paragraph.
-.CDE
-.
-.IP ""
+.Ed
+.Pp
will produce
-.
-.CDS 8
-Inline footnote<a href="#inline-footnote-1"
+.Bd -literal -offset Ds
+Inline footnote<a href="#inline-footnote-1"
id="inline-footnote-text-1"><sup>1</sup></a> in a
paragraph.
<hr>
<p id="inline-footnote-1"><a href="#inline-footnote-text-1">
-1.</a> Footnote text</p>
-.CDE
-.RE
-.
-.IP
+1.</a> Footnote text
+.Ed
+.Pp
The horizontal rule and the list of footnotes is output only once, before the
-end of
-.SM HTML
-document body. Rule and the list of footnotes can be surrounded by a div with
-the \[lq]\fCfootnotes\fR\[rq] id by setting the
-.SM YAML
-variable
-.I add-footnote-div
-to \[lq]1\[rq] (see
-.BR add-footnote-div ).
-.
-.IP
+end of HTML document body.
+Rule and the list of footnotes can be surrounded by a div with the
+.Dq Dv footnotes
+id by setting the YAML variable
+.Va add-footnote-div
+to
+.Dq 1
+(see
+.Sx add\-footnote\-div Ns ).
+.Pp
Inline and regular footnotes can be used at the same time, but they don't share
-the numbering. This doesn't affect functionality, but it does affect
-presentation, as some footnote numbers will overlap. As a result, whenever
-.B slweb
+the numbering.
+This doesn't affect functionality, but it does affect presentation, as some
+footnote numbers will overlap.
+As a result, whenever
+.Nm
encounters both footnote types in the same document, a warning will be issued to
-.IR stderr .
-.
-.IP \[bu]
-.BR Headings .
-A line starting with \fC#\fR followed by space will be put inside
-\fC<h?></h?>\fR, where \fC?\fR stands for 1-4, depending on the number of
-hash signs. Tags will have \fCid\fR attributes set to \fCheading-?\fR, with
-\fC?\fR set to the number representing its position within the list of all
-headings.
-.
-.IP \[bu]
-.BR "Horizontal rules" .
-Three dashes at the start of the line will produce a \fC<hr>\fR in the output.
-As this Markdown feature clashes with
-.SM YAML
-block boundaries, it will work only if
-.SM YAML
-block is present in the input and before the three dashes for the horizontal
-rule. Any text following the three dashes on the same line will be ignored.
-.
-.IP
-Alternatively, three asterisks (\fC***\fR) can be used instead of dashes,
-avoiding the necessity for a
-.SM YAML
-block preceding the asterisks.
-.
-.IP \[bu]
-.BR Images .
+.Pa stderr .
+.El
+.It
+.Sy Headings .
+A line starting with
+.Ql #
+followed by space will be put inside
+.Ql <h?></h?> ,
+where
+.Ql "?"
+stands for 1-4, depending on the number of hash signs.
+Tags will have
+.Cm id
+attributes set to
+.Ql heading-\[u003f] ,
+with
+.Ql "?"
+set to the number representing its position within the list of all headings.
+.It
+.Sy "Horizontal rules" .
+Three dashes at the start of the line will produce a
+.Ql <hr>
+in the output.
+As this Markdown feature clashes with YAML block boundaries, it will work only
+if YAML block is present in the input and before the three dashes for the
+horizontal rule.
+Any text following the three dashes on the same line will be ignored.
+.Pp
+Alternatively, three asterisks
+.Pq Ql "***"
+can be used instead of dashes, avoiding the necessity for a YAML block preceding
+the asterisks.
+.It
+.Sy Images .
Similar to links (see
-.BR Links ),
+.Sx Links Ns ),
images can be added by using:
-.
-.CDS 8
+.Bd -literal -offset Ds
-.CDE
-.
-.IP
+.Ed
+.Pp
Which will produce:
-.
-.CDS 8
+.Bd -literal -offset Ds
<figure>
<a href="/path/to/image.png" title="Some title" class="image"
- target="_blank"><img src="/path/to/image.png" alt="Some title"
+ target="_blank"><img src="/path/to/image.png" alt="Some title"
width="100" height="50" ></a><figcaption>Some title</figcaption>
</figure>
-.CDE
-.
-.IP
-The attributes \fCwidth\fR and \fCheight\fR will be determined automatically
-using the command
-.BR identify (1)
-(if present), provided the \fCsrc\fR attribute contains a valid file path. (Also
-see
-.BR image-file-prefix ).
-.
-.IP
-As with links, a form similar to the \[lq]regular form\[rq] of links can also be
-used, using the image id instead of the direct
-.SM URL.
-.
-.IP
-If the additional link or \fC<figure>\fR/\fC<figcaption>\fR tags are not
-desirable, they can be turned off by setting
-.B add-image-links
+.Ed
+.Pp
+The attributes
+.Cm width
and
-.B add-figcaption
-to \[lq]0\[rq].
-.
-.IP \[bu]
-.BR "Keyboard tags" .
-Text inside \fC||double bars||\fR will be put inside \fC<kbd></kbd>\fR tags. As
-with backticks, any \[lq]less-than\[rq] character will be converted to
-\fC<\fR.
-.
-.IP \[bu]
-.BR "Line breaks" .
-Two spaces followed by a newline will become \fC<br>\fR.
-.
-.IP \[bu]
-.BR Links .
-.
-.RS
-.IP \- 4
-.BR "Inline links" .
-The construct \fC[A link](https://example.com)\fR will be converted into \fC<a
-href="https://example.com">A link</a>\fR.
-.
-.IP ""
-Special case is the form \fC[=somemacro Link title](https://anything)\fR which
-prepends the body of a macro
-.I somemacro
-into the \fC<a></a>\fR tag (here broken into multiple lines for clarity):
-.
-.CDS 8
+.Cm height
+will be determined automatically using the command
+.Xr identify 1
+(if present), provided the
+.Cm src
+attribute contains a valid file path. (Also see
+.Va image-file-prefix Ns ).
+.Pp
+As with links, a form similar to the
+.Dq regular form
+of links can also be used, using the image id instead of the direct URL.
+.Pp
+If the additional link or
+.Ql "<figure>" Ns
+.Pf / Ns Ql <figcaption>
+tags are not desirable, they can be turned off by setting
+.Va add-image-links
+and
+.Va add-figcaption
+to
+.Dq 0 .
+.It
+.Sy "Keyboard tags" .
+Text inside
+.Ql ||double bars|\[u007c]
+will be put inside
+.Ql <kbd></kbd>
+tags.
+As with backticks, any
+.Dq less\-than
+character will be converted to
+.Ql <\[u003b] .
+.It
+.Sy "Line breaks" .
+Two spaces followed by a newline will become
+.Ql <br> .
+.It
+.Sy Links .
+.Bl -dash -width 1m
+.It
+.Sy "Inline links" .
+The construct
+.Ql [A link](https://example.com)
+will be converted into
+.Ql <a href="https://example.com">A link</a> .
+.Pp
+Special case is the form
+.Dl [= Ar somemacro No Link title](https://anything)
+which prepends the body of a macro
+.Ar somemacro
+into the
+.Ql <a></a>
+tag (here broken into multiple lines for clarity):
+.Bd -literal -offset Ds
<a href="https://anything">
<!-- contents of somemacro -->
Link title</a>
-.CDE
-.
-.IP "" 4
-This can, for example, be used to add
-.SM SVG
-icons to links. See
-.BR Macros .
-.
-.IP "" 4
-Also, the form \fC[(Link title)](http://asite.com)\fR will surround the link
-title (text between \fC<a></a>\fR tags) with \fC<span></span>\fR, like so:
-.
-.CDS 8
+.Ed
+.Pp
+This can, for example, be used to add SVG icons to links.
+See
+.Sx Macros .
+.Pp
+Also, the form
+.Ql [(Link title)](http://asite.com)
+will surround the link title (text between
+.Ql <a></a>
+tags) with
+.Ql <span></span> ,
+like so:
+.Bd -literal -offset Ds
<a href="http://asite.com"><span>Link title</span></a>
-.CDE
-.
-.IP
-This allows for separate styling of link text. It can be combined with the
-macro-form:
-.
-.CDS 8
+.Ed
+.Pp
+This allows for separate styling of link text.
+It can be combined with the macro\-form:
+.Bd -literal -offset Ds
[=somemacro (Link title)](http://asite.com)
-.CDE
-.
-.IP
+.Ed
+.Pp
It will prepend the body of a macro
-.I somemacro
-outside of the \fC<span></span>\fR:
-.
-.CDS 8
+.Ar somemacro
+outside of the
+.Ql <span></span> :
+.Bd -literal -offset Ds
<a href="http://asite.com">
<!-- contents of somemacro -->
<span>Link title</span></a>
-.CDE
-.
-.IP
-Exception is the form \fC[Some text (parenthesized)](https://somelink)\fR, which
-won't output \fC<span>\fR tags, and will simply include the parentheses in the
-output instead. This form doesn't apply to macro-form \fC[=macro Some
-(text)](http://link)\fR, which will always output \fC<span>\fR tags.
-.
-.IP \-
-.BR "Regular links" .
+.Ed
+.Pp
+Exception is the form
+.Dl [Some text (parenthesized)](https://somelink) ,
+which won't output
+.Ql <span>
+tags, and will simply include the parentheses in the output instead.
+This form doesn't apply to macro-form
+.Dl [=macro Some (text)](http://link) ,
+which will always output
+.Ql <span>
+tags.
+.It
+.Sy "Regular links" .
Everything said about inline links applies to regular links, with the exception
-that instead of the parenthesized
-.SM URL,
-link text inside brackets should be followed by link id (different than the
-\[lq]\fCid\fR\[rq]
-.IR attribute! )
-inside brackets, and a
-separate definition of that link id is needed, usually near the end of input.
-.
-.IP
+that instead of the parenthesized URL, link text inside brackets should be
+followed by link id (different than the
+.Cm id
+.Em attribute\[u0021] )
+inside brackets, and a separate definition of that link id is needed, usually
+near the end of input.
+.Pp
For example:
-.
-.CDS 8
+.Bd -literal -offset Ds
Here's a link to [my website][mw].
[mw]: https://mysite.com
-.CDE
-.
-.IP
+.Ed
+.Pp
will produce:
-.
-.CDS 8
-<p>Here's a link to <a href="https://mysite.com">my
-website</a>.</p>
-.CDE
-.
-.IP
+.Bd -literal -offset Ds
+<p>Here's a link to <a href="https://mysite.com">my website</a>.
+.Ed
+.Pp
This can help reduce the amount of code in the text of the page.
-.RE
-.
-.IP \[bu] 4
-.BR Lists .
-Lines starting with a dash (\fC\-\fR), an asterisk (\fC*\fR) or lowercase
-\[lq]o\[rq], followed by a space, will start an unordered list (if used for the
-first time) and start a list item. Input:
-.
-.CDS 8
+.El
+.It
+.Sy Lists .
+Lines starting with a dash
+.Pf "(" Ql - Ns
+),
+an asterisk
+.Pf "(" Ql * )
+or lowercase
+.Dq o ,
+followed by a space, will start an unordered list (if used for the first time)
+and start a list item.
+Input:
+.Bd -literal -offset Ds
Colors are:
- Red
@@ -472,88 +458,88 @@ Colors are:
- Blue
and so on.
-.CDE
-.
-.IP
+.Ed
+.Pp
will produce:
-.
-.CDS 8
-<p>Colors are:</p>
+.Bd -literal -offset Ds
+<p>Colors are:
<ul>
<li><p>Red
-</p></li>
+</li>
<li><p>Green
-</p></li>
-<li><p>Blue</p>
+</li>
+<li><p>Blue
</li></ul>
-<p>And so on.</p>
-.CDE
-.
-.IP
+<p>And so on.
+.Ed
+.Pp
Indenting a line after a blank line with two spaces will create a paragraph
within the list item, otherwise it will end the list:
-.
-.CDS 8
+.Bd -literal -offset Ds
- This is a text inside a list item.
Remarkably, this paragraph is as well.
- This is already a second item.
This is after the list.
-.CDE
-.
-.IP
+.Ed
+.Pp
will produce:
-.
-.CDS 8
-<ul>
-<li><p>This is a text inside a list item.</p>
+.Bd -literal -offset Ds
+<ul><li><p>This is a text inside a list item.
<p>Remarkably, this paragraph is as well.
-</p></li>
-<li><p>This is already a second item.</p></li></ul>
-<p>This is after the list.</p>
-.CDE
-.
-.IP
+</li>
+<li><p>This is already a second item.</li></ul>
+<p>This is after the list.
+.Ed
+.Pp
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.
-.
-.IP \[bu] 4
-.BR "Non\-breaking hyphen" .
-Tilde followed by a hyphen (\fC~-\fR) will insert \fC‑\fR in the output.
-.
-.IP \[bu] 4
-.BR "Non\-breaking space" .
-Two consecutive tildes (\fC~~\fR) will produce \fC \fR in the output.
-.
-.IP \[bu] 4
-.BR Paragraphs .
-Text surrounded by newlines will be put inside \fC<p></p>\fR tags. See
-.SM "KNOWN LIMITATIONS."
-.
-.IP \[bu] 4
-.BR Strikethrough .
-Text surrounded by tildes (\fC~\fR) will be put inside \fC<s></s>\fR.
-.
-.IP \[bu] 4
-.BR Tables .
-Lines starting with vertical bars (\fC|\fR) will be transformed into
-.SM HTML
-tables. The first such line is treated as a header row, second as the alignment
-specifier (currently ignored), and the rest regular rows. Table cells and header
-cells are specified by additional bar characters. For example, input:
-.
-.CDS 8
+.It
+.Sy "Non\-breaking hyphen" .
+Tilde followed by a hyphen
+.Pf "(" Ql ~- )
+will insert
+.Ql ‑\[u003b]
+in the output.
+.It
+.Sy "Non\-breaking space" .
+Two consecutive tildes
+.Pf "(" Ql ~~ )
+will produce
+.Ql  \[u003b]
+in the output.
+.It
+.Sy Paragraphs .
+Text surrounded by newlines will be prepended by
+.Ql <p>
+tag.
+See
+.Sx "Known limitations" .
+.It
+.Sy Strikethrough .
+Text surrounded by tildes
+.Pf "(" Ql ~ )
+will be put inside
+.Ql <s></s> .
+.It
+.Sy Tables .
+Lines starting with vertical bars
+.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.
+Table cells and header cells are specified by additional bar characters.
+For example, input:
+.Bd -literal -offset Ds
| Month | Jan | Feb | Mar | Apr |
|-------|-----|-----|-----|-----|
| Qty | 2.35| 1.2 | 8 | 15 |
-.CDE
-.
-.IP "" 4
+.Ed
+.Pp
will be transformed into:
-.
-.CDS 8
+.Bd -literal -offset Ds
<table>
<thead>
<tr><th> Month </th><th> Jan </th><th> Feb </th><th> Mar </th>
@@ -564,20 +550,17 @@ will be transformed into:
<td> 15 </td></tr>
</tbody>
</table>
-.CDE
-.
-.IP "" 4
-.B Partial tables
-are a modification of Markdown tables, allowing them to be combined with the
-.SM TSV
-or
-.SM CSV
-directive. In order for tables to work with templating, they need two additional
-lines at the top and the bottom, to mark the start and the end of the table. All
-the lines in partial tables need to start with \[lq]\fC|@\fR\[rq], with only the
-character following at-mark being different:
-.
-.CDS 8
+.Ed
+.It
+.Sy Partial tables
+are a modification of Markdown tables, allowing them to be combined with the TSV
+or CSV directive.
+In order for tables to work with templating, they need two additional lines at
+the top and the bottom, to mark the start and the end of the table.
+All the lines in partial tables need to start with
+.Ql | ,
+with only the character following at-mark being different:
+.Bd -literal -offset Ds
|@\\------|-----|-----|-----|-----|
{tsv "../tsv/sales" 1}
|@# $#1 | $#2 | $#3 | $#4 | $#5 |
@@ -587,179 +570,233 @@ character following at-mark being different:
|@ $1 | $2 | $3 | $4 | $5 |
{/tsv}
|@/------|-----|-----|-----|-----|
-.CDE
-.
-.IP "" 4
+.Ed
+.Pp
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
-.BR "TSV/CSV templating" .
-.
-.SS Math mode
-.
-.LP
-Math mode is supported through KaTeX. With
-.BR katex
-installed, anything between dollar signs (\fC$\fR) will be transformed into
-MathML and
-.SM HTML
-markup. To generate display math, use double dollar signs (\fC$$\fR). The text
-between the dollar signs in both cases should be LaTeX source code, and is
-passed to
-.BR katex .
+example only for aesthetic purposes.
+See
+.Sx "TSV/CSV templating" .
+.El
+.
+.Ss "Math mode"
+Math mode is supported through KaTeX.
+With
+.Nm katex
+installed, anything between dollar signs
+.Pf "(" Ql $ )
+will be transformed into MathML and HTML markup.
+To generate display math, use double dollar signs
+.Pf "(" Ql $$ Ns
+).
+The text between the dollar signs in both cases should be LaTeX source code, and
+is passed to
+.Nm katex .
The KaTeX stylesheet is not included, and needs to be included separately
through the
-.B stylesheet
+.Va stylesheet
or
-.B inline-stylesheet
-.SM YAML
-variables (see
-.BR stylesheet ", " inline-stylesheet ).
-.
-.SS Directives
-.
-.IP \[bu] 4
-.BR "Brand \[lq]watermark\[rq]" .
-Directive \fC{made\-by}\fR results in a div to be output at the end of the
-document, with the id \fCmade\-by\fR containing the \[lq]watermark\[rq] text and
-a link to the
-.B slweb
+.Va inline-stylesheet
+YAML variables (see
+.Sx stylesheet ,
+.Sx inline-stylesheet Ns ).
+.
+.Ss Directives
+.Bl -bullet -width 1m
+.It
+.Bf Sy
+Brand
+.Dq watermark Ns
+.Ef
+\&.
+Directive
+.Ql {made\-by}
+results in a div to be output at the end of the document, with the id
+.Ic made\-by
+containing the
+.Dq watermark
+text and a link to the
+.Nm
home page.
-.
-.IP \[bu] 4
-.BR "General tags" .
-Directive \fC{sometag}{/sometag}\fR will be transformed into
-\fC<sometag></sometag>\fR.
-.
-.RS
-.IP \- 4
-.BR "Class attributes" .
-Directive \fC{tag.myclass mysecondclass}{/tag}\fR will be transformed into
-\fC<tag class="myclass mysecondclass"></tag>\fR. Only one class attribute is
-permitted per tag directive (subsequent dots will be inserted as part of the
-\fCclass\fR attribute), but you can include multiple classes by separating them
-with a space, just like in
-.SM HTML,
-and you can have both a class attribute and an id attribute per tag.
-
-A variation of this is to use a special form \fC{.myclass}{/.myclass}\fR, which
-will be transformed into \fC<div class="myclass"></div>\fR.
-.
-.IP \-
-.BR "Id attributes" .
-Directive \fC{tag#myid}{/tag}\fR will be transformed into \fC<tag
-id="myid"></tag>\fR. Only one id attribute is permitted per tag directive
-(subsequent hash signs will be included as part of the \fCid\fR attribute), and
-you can have both an id attribute and a class attribute per tag.
-
-A variation of this is to use a special form \fC{#myid}{/#myid}\fR, which will
-be transformed into \fC<div id="myid"></div>\fR.
-.RE
-.
-.IP \[bu]
-.BR Includes .
-Directive \fC{include "somefile"}\fR will fork, parse
-.I somefile.slw
+.It
+.Sy "General tags" .
+Directive
+.Ql {sometag}{/sometag}
+will be transformed into
+.Ql <sometag></sometag> .
+.It
+.Sy "Class attributes" .
+Directive
+.Ql {tag.myclass mysecondclass}{/tag}
+will be transformed into
+.Ql <tag class="myclass mysecondclass"></tag> .
+Only one class attribute is permitted per tag directive (subsequent dots will be
+inserted as part of the
+.Cm class
+attribute), but you can include multiple classes by separating them with a
+space, just like in HTML, and you can have both a class attribute and an id
+attribute per tag.
+.Pp
+A variation of this is to use a special form
+.Ql {.myclass}{/.myclass} ,
+which will be transformed into
+.Ql <div class="myclass"></div> .
+.It
+.Sy "Id attributes" .
+Directive
+.Ql {tag#myid}{/tag}
+will be transformed into
+.Ql <tag id="myid"></tag> .
+Only one id attribute is permitted per tag directive (subsequent hash signs will
+be included as part of the
+.Cm id
+attribute), and you can have both an id attribute and a class attribute per tag.
+.Pp
+A variation of this is to use a special form
+.Ql {#myid}{/#myid} ,
+which will be transformed into
+.Ql <div id="myid"></div> .
+.It
+.Sy Includes .
+Directive
+.Ql {include "somefile"}
+will fork, parse
+.Pa somefile.slw
(related to
-.IR basedir )
-and output the resulting
-.SM HTML
-as if the option \fC\-\-body\-only\fR was specified. All
-.SM YAML
-variables will be preserved.
-.
-.IP \[bu]
-.BR Macros .
-Macros can be declared using the directive \fC{=!macroname}{/=!macroname}\fR,
+.Pa basedir )
+and output the resulting HTML as if the option
+.Fl \-body\-only
+was specified.
+All YAML variables will be preserved.
+.It
+.Sy Macros .
+Macros can be declared using the directive
+.Ql {=! Ns Ar macroname Ns }{/=! Ns Ar macroname Ns } ,
where
-.I macroname
-is the name of the macro. Anything between those two tags will then become the
-body of a macro. Whenever \fC{=macroname}\fR is subsequently encountered in the
-file, it will be replaced by the macro body. 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.
-.
-.IP \[bu]
-.BR "Previous Git commit information" .
-Directive \fC{git-log}\fR is converted into a div with the id \fCgit-log\fR
+.Ar macroname
+is the name of the macro.
+Anything between those two tags will then become the body of a macro.
+Whenever
+.Ql {= Ns Ar macroname Ns }
+is subsequently encountered in the file, it will be replaced by the macro body.
+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" .
+Directive
+.Ql {git\-log}
+is converted into a div with the id
+.Ql git-log
containing the information about the previous commit (as having information
about the current commit would be impossible).
-.
-.IP \[bu]
-.BR "Subdirectory inclusion (blogging directive)" .
-The directive \fC{incdir "\f[CI]dirname\f[CR]" \f[CI]num\f[CR]
-=\f[CI]macroname\f[CR] listonly}\fR
-.RI ( num ,
-.I macroname
-and the literal \[lq]\fClistonly\fR\[rq] are optional) will be expanded as
-follows:
-.
-.RS
-.nr list 1 1
-.IP \n[list]. 4
-A \fC<ul class="incdir">\fR tag will be inserted into the document instead of
-the directive.
-.
-.IP \n+[list].
+.It
+.Sy "Subdirectory inclusion (blogging directive)" .
+The directive
+.Dl {incdir \(dq Ns Ar dirname Ns \(dq Ar num No = Ns Ar macroname No listonly}
+.Pf "(" Ar num ,
+.Ar macroname
+and the literal
+.Ql Cm listonly
+are optional) will be expanded as follows:
+.Bl -enum -offset Ds
+.It
+A
+.Ql <ul class="incdir">
+tag will be inserted into the document instead of the directive.
+.It
For every subdirectory of
-.IR dirname ,
+.Ar dirname ,
relative to current directory and up to
-.I num
-(if present) or 5 (if omitted) total subdirectories, a \fC<li>\fR
-tag will be inserted into the \fCul\fR tag.
-.IP
-If the parameter \fClistonly\fR was specified, a \fC<li>\fR tag will instead be
-inserted for every
-.I .slw
+.Ar num
+(if present) or 5 (if omitted) total subdirectories, a
+.Ql <li>
+tag will be inserted into the
+.Ql ul
+tag.
+.Pp
+If the parameter
+.Cm listonly
+was specified, a
+.Ql <li>
+tag will instead be inserted for every
+.Pa .slw
file within each of the subdirectories, sorted in reverse lexicographical order.
-In this case, each \fC<li>\fR will contain a permalink with a title preceded by
-a timestamp formatted according to \fClist_timestamp_format\fR. Title and date
-are read from each
-.I .slw
+In this case, each
+.Ql <li>
+will contain a permalink with a title preceded by a timestamp formatted
+according to
+.Va list_timestamp_format .
+Title and date are read from each
+.Pa .slw
file, as YAML variables
-.B title
-and
-.BR date .
+.Va title
+and
+.Va date .
For this case, processing of the
-.I incdir
+.Ic incdir
directive stops here.
-.
-.IP \n+[list].
-A \fC<details>\fR tag will be inserted into each \fC<li>\fR tag.
-.
-.IP \n+[list].
-Inside of the \fC<details>\fR tag, a \fC<summary>\fR tag will be inserted with
-the name of the subdirectory. If
-.I macroname
+.It
+A
+.Ql <details>
+tag will be inserted into each
+.Ql <li>
+tag.
+.It
+Inside of the
+.Ql <details>
+tag, a
+.Ql <summary>
+tag will be inserted with the name of the subdirectory.
+If
+.Ar macroname
is present, the name of the subdirectory will be prepended with the body of a
macro
-.I macroname
-(for example, this can be used to include custom
-.SM SVG
-markup as arrows).
-.
-.IP \n+[list].
-After \fC<summary>\fR tag, a \fC<div>\fR tag will be inserted into
-\fC<details>\fR, containing the concatenated output from processing each of the
-.I .slw
+.Ar macroname
+(for example, this can be used to include custom SVG markup as arrows).
+.It
+After
+.Ql <summary>
+tag, a
+.Ql <div>
+tag will be inserted into
+.Ql <details> ,
+containing the concatenated output from processing each of the
+.Pa .slw
files inside that subdirectory in reverse lexicographical order, in a manner
similar to the
-.I include
-directive. (See
-.BR Includes " and " date ", " ext-in-permalink ", " permalink-url ", "
-.BR samedir-permalink " variables.)"
-The output of each file will be surrounded by an \fC<article>\fR tag.
-.
-.PP
+.Ic include
+directive.
+(See
+.Sx Includes
+and
+.Sx date ,
+.Sx ext\-in\-permalink ,
+.Sx permalink\-url ,
+.Sx samedir\-permalink
+variables.)
+The output of each file will be surrounded by an
+.Ql <article>
+tag.
+.El
+.Pp
If the included file has the variable
-.B incdir-only-summary
-set to \[lq]1\[rq], only the text within the summary marks (\fC/-\fR and
-\fC-/\fR) will be output, and if the variable
-.B incdir-footer-permalink-text
-is also set, \fC<footer>\fR element with a permalink to the article will be
-added after it.
-Example: (\fCposts/blog-post.slw\fR)
-.CDS 4
+.Va incdir-only-summary
+set to
+.Dq 1 ,
+only the text within the summary marks
+.Pf "(" Ql /-
+and
+.Ql -/ )
+will be output, and if the variable
+.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 )
+.Bd -literal -offset Ds
---
incdir-only-summary: 1
---
@@ -769,16 +806,18 @@ The quick brown fox jumps over the lazy sleeping dog. The quick brown fox jumps
over the lazy sleeping dog. The quick brown fox jumps over the lazy sleeping
dog. The quick brown fox jumps over the lazy sleeping dog. The quick brown fox
jumps over the lazy sleeping dog.
-.CDE
-(\fCblog-index.slw\fR)
-.CDS 4
+.Ed
+.Pp
+.Pf ( Pa blog-index.slw )
+.Bd -literal -offset Ds
---
incdir-footer-permalink-text: Click here!
---
{incdir "."}
-.CDE
+.Ed
+.Pp
will produce
-.CDS 4
+.Bd -literal -offset Ds
<!DOCTYPE html>
<html lang="en">
<head>
@@ -804,9 +843,12 @@ This article is great!<footer>
</ul>
</body>
</html>
-.CDE
-for \fCblog-index.slw\fR, and
-.CDS 4
+.Ed
+.Pp
+for
+.Pa blog-index.slw ,
+and
+.Bd -literal -offset Ds
<!DOCTYPE html>
<html lang="en">
<head>
@@ -821,84 +863,98 @@ for \fCblog-index.slw\fR, and
The quick brown fox jumps over the lazy sleeping dog. The quick brown fox jumps
over the lazy sleeping dog. The quick brown fox jumps over the lazy sleeping
dog. The quick brown fox jumps over the lazy sleeping dog. The quick brown fox
-jumps over the lazy sleeping dog.</p>
+jumps over the lazy sleeping dog.
</body>
</html>
-.CDE
-for \fCposts/blog-post.slw\fR.
-.RE
-.
-.IP \[bu]
-.BR "TSV/CSV templating" .
-Directive \fC{tsv "\f[CI]tsvfile\f[CR]" \f[CI]iter\f[CR]}{/tsv}\fR marks a
-template.
-Whatever is between \fC{tsv}\fR and \fC{/tsv}\fR will be processed by
-.B slweb
-and collected as a template. Afterwards, file \fItsvfile.tsv\fR will be read and
-for each of its lines (up to
-.IR iter ,
-if present) the collected template will be output, substituting each occurrence
-of a register mark \fC$\f[CI]n\fR (where \fIn\fR is between 1 and 9, inclusive)
-with the corresponding
-.SM TSV
-field of the read line. All of this applies to the similar \fC{csv}\fR directive
+.Ed
+.Pp
for
-.SM CSV
-files. In the case of
-.SM CSV
-files, they need to use semicolons (;) or commas (,) as delimiters (or set
-.B csv-delimiter
-as a
-.SM YAML
-variable in the calling
-.I .slw
-file) and double quotation marks (") as field boundaries. First line in the
-.SM TSV
-file is parsed as a header and associated with register marks \fC$#1\fR to
-\fC$#9\fR. The symbol $ is represented as \fC$$\fR. Consequently, math modes
-(both inline and display) cannot be used within templates.
-.
-.IP "" 8
+.Pa posts/blog-post.slw .
+.It
+.Sy "TSV/CSV templating" .
+Directive
+.Dl {tsv \(dq Ns Ar tsvfile Ns \(dq Ar iter Ns }{/tsv}
+marks a template.
+Whatever is between
+.Ql {tsv}
+and
+.Ql {/tsv}
+will be processed by
+.Nm
+and collected as a template.
+Afterwards, file
+.Pa tsvfile.tsv
+will be read and for each of its lines (up to
+.Ar iter ,
+if present) the collected template will be output, substituting each occurrence
+of a register mark
+.Ql $ Ns Ar n
+(where
+.Ar n
+is between 1 and 9, inclusive) with the corresponding TSV field of the read
+line.
+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 ";" )
+or commas
+.Pf "(" Ql "," )
+as delimiters (or set
+.Va csv\-delimiter
+as a YAML variable in the calling
+.Pa .slw
+file) and double quotation marks
+.Pf "(" Ql "\(dq" )
+as field boundaries.
+First line in the TSV file is parsed as a header and associated with register
+marks
+.Ql $#1
+to
+.Ql $#9 .
+The symbol
+.Ql $
+is represented as
+.Ql $$ .
+Consequently, math modes (both inline and display) cannot be used within
+templates.
+.Pp
Parts of the template can be conditionally rendered by using the construct:
-.
-.CDS 8
-$?\f[CI]n\fR
- <!-- code to include if $\f[CI]n\f[CR] nonempty -->
+.Bd -literal -offset Ds
+$?n
+ <!-- code to include if $n nonempty -->
$?!
- <!-- code to include if $\f[CI]n\f[CR] empty -->
+ <!-- code to include if $n empty -->
$?/
-.CDE
-.
-.IP "" 4
-where \fIn\fR is between 1 and 9, inclusive. For example, having a file
-\fIsales.tsv\fR:
-.
-.CDS 8
+.Ed
+.Pp
+where
+.Ar n
+is between 1 and 9, inclusive.
+For example, having a file
+.Pa sales.tsv :
+.Bd -literal -offset Ds
Item Q1 2020 Q2 2020 Q3 2020 Q4 2020
Toothpick 15.2 12 10
Teapot 1.2 5 3.5
-.CDE
-.
-.IP "" 4
+.Ed
+.Pp
We can write
-.
-.CDS 8
+.Bd -literal -offset Ds
{tsv "sales"}
{.sales-segment}
-$#1 {q}$1{/q} sales by quarter for the last year in
+$#1 {q}$1{/q} sales by quarter for the last year in
thousands of units sold (for $$) were as follows:
-$?2{.q1}$2{/.q1}$?!{.q1 na}N/A{/.q1}$?/
+$?2{.q1}$2{/.q1}$?!{.q1 na}N/A{/.q1}$?/
$?3{.q2}$3{/.q2}$?!{.q2 na}N/A{/.q2}$?/
$?4{.q3}$4{/.q3}$?!{.q3 na}N/A{/.q3}$?/
$?5{.q4}$5{/.q4}$?!{.q4 na}N/A{/.q4}$?/
{/.sales-segment}
{/tsv}
-.CDE
-.
-.IP "" 4
+.Ed
+.Pp
to get:
-.
-.CDS 8
+.Bd -literal -offset Ds
<div class="sales-segment">
Item <q>Toothpick</q> sales by quarter for the last year in
thousands of units sold (for $) were as follows:
@@ -916,262 +972,309 @@ thousands of units sold (for $) were as follows:
<div class="q3">5</div>
<div class="q4">3.5</div>
</div>
-.CDE
-.
-.IP "" 4
-.SM TSV
-directives can't be nested and doing so will produce an error.
-.
-.IP "" 4
-The directives \f[CR]{csv\-count "\f[CI]csvfile\f[CR]"}\fR and \f[CR]{tsv\-count
-"\f[CI]tsvfile\f[CR]"}\fR output the number of \[lq]records\[rq] in the file
-\fIcsvfile.csv\fR or \fItsvfile.tsv\fR (number of lines minus one for the header
-row).
+.Ed
+.Pp
+TSV directives can't be nested and doing so will produce an error.
+.Pp
+The directives
+.Ql {csv\-count \(dq Ns Ar csvfile Ns \(dq}
+and
+.Ql {tsv\-count \(dq Ns Ar tsvfile Ns \(dq}
+output the number of
+.Dq records
+in the file
+.Pa csvfile.csv
+or
+.Pa tsvfile.tsv
+(number of lines minus one for the header row).
No newline is output following the number.
-.
-.SS Special YAML variables
-.
-.IP \[bu] 4
-.BR add-article-header .
-If set to \[lq]1\[rq], title, date and header text at the beginning of the
-output body will be enclosed in a \fC<header>\fR tag.
-.
-.IP \[bu]
-.BR add-figcaption .
-If set to \[lq]0\[rq], \fC<figure>\fR and \fC<figcaption>\fR tags around images
-will not be added (otherwise they will by default, see
-.BR Images ).
-.
-.IP \[bu]
-.BR add-footnote-div .
-If set to \[lq]1\[rq], list of footnotes preceded by a horizontal rule will be
-surrounded with a div having the id \[lq]\fCfootnotes\fR\[rq] (see
-.BR Footnotes ).
-.
-.IP \[bu]
-.BR add-image-links .
-If set to \[lq]0\[rq], links around images will not be added (otherwise they
-will by default, see
-.BR Images ).
-.
-.IP \[bu]
-.BR author .
+.El
+.
+.Ss Special YAML variables
+.Bl -bullet -width 1m
+.It
+.Va add\-article\-header .
+If set to
+.Dq 1 ,
+title, date and header text at the beginning of the output body will be enclosed
+in a
+.Ql <header>
+tag.
+.It
+.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 ).
+.It
+.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 ).
+.It
+.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 ).
+.It
+.Va author .
If set, the contents of this variable will be added to the start of the output
-body (inside a \fC<header>\fR tag if it is set), surrounded by
-\fC<address></address>\fR.
-.
-.IP \[bu]
-.BR canonical .
-Contents of this variable will be added as a value of a \fCrel\fR attribute for
-the \fC<link rel="canonical">\fR tag.
-.
-.IP \[bu]
-.BR csv-delimiter .
-Changes the delimiter used for
-.I .csv
-file parsing. By default, this will be a semicolon\~(;). See
-.BR "CSV templating" .
-.
-.IP \[bu]
-.BR date .
-If present, this variable, assumed to be in
-.SM ISO
-8601
-.SM UTC
-datetime format, will be parsed to determine the timestamp in permalinks
-generated by the
-.I incdir
-directive. The actual values used depend on the source-level constants
-.I article_timestamp_format
-(for \fCincdir\fR without the argument \[lq]listonly\[rq]) and
-.I list_timestamp_format
-(for \fCincdir\fR with the argument \[lq]listonly\[rq]).
-.
-.IP \[bu]
-.BR ext-in-permalink .
-If set to \[lq]0\[rq], permalinks generated by the
-.I incdir
+body (inside a
+.Ql <header>
+tag if it is set), surrounded by
+.Ql <address></address> .
+.It
+.Va canonical .
+Contents of this variable will be added as a value of a
+.Ql rel
+attribute for the
+.Ql <link rel="canonical">
+tag.
+.It
+.Va csv\-delimiter .
+Changes the delimiter used for
+.Pa .csv
+file parsing.
+By default, this will be a semicolon\
+.Pf "(" Ns Ql ; Ns
+).
+See
+.Sx "CSV templating" .
+.It
+.Va date .
+If present, this variable, assumed to be in ISO\ 8601 UTC datetime format, will
+be parsed to determine the timestamp in permalinks generated by the
+.Ic incdir
+directive.
+The actual values used depend on the source\-level constants
+.Va article_timestamp_format
+(for
+.Ic incdir
+without the argument
+.Cm listonly )
+and
+.Va list_timestamp_format
+(for
+.Ic incdir
+with the argument
+.Cm listonly Ns ).
+.It
+.Va ext\-in\-permalink .
+If set to
+.Dq 0 ,
+permalinks generated by the
+.Ic incdir
directive will not have the extension included in the
-.I href
-attribute. For example, instead of \fCblog/2020/august.html\fR, the resulting
-permalink will have \fCblog/2020/august\fR.
-.
-.IP \[bu]
-.BR favicon-url .
-If present, this
-.SM URL
-will be used as a favicon
-.SM URL
-instead of the default, \fC/favicon.ico\fR.
-.
-.IP \[bu]
-.BR feed ", " feed-type ", " feed-desc .
-If all are present, contents of those variables will be added as \fIhref\fR,
-\fItype\fR and \fItitle\fR attributes (respectively) to the \fC<link
-rel="alternate">\fR tag in the page's \fC<head>\fR.
-.
-.IP \[bu]
-.BR header-text .
+.Cm href
+attribute.
+For example, instead of
+.Pa blog/2020/august.html ,
+the resulting permalink will have
+.Pa blog/2020/august .
+.It
+.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 .
+If all are present, contents of those variables will be added as
+.Cm href ,
+.Cm type
+and
+.Cm title
+attributes (respectively) to the
+.Ql <link rel="alternate">
+tag in the page's
+.Ql <head> .
+.It
+.Va header\-text .
The contents of this variable will be added to the start of the output body
-(inside a \fC<header>\fR tag if it is set), surrounded by \fC<p></p>\fR.
-.
-.IP \[bu]
-.BR image-file-prefix .
-If present, the value of \fCsrc\fR attribute will be appended to the contents of
-this variable, with path separator added as necessary, when determining the
-actual file path to pass to the
-.BR identify (1)
-command. Otherwise, \fCsrc\fR is appended to \[lq].\[rq].
-.
-.IP \[bu]
-.BR incdir-footer-permalink-text .
+(inside a
+.Ql <header>
+tag if it is set), preceeded by
+.Ql <p> .
+.It
+.Va image\-file\-prefix .
+If present, the value of
+.Cm src
+attribute will be appended to the contents of this variable, with path separator
+added as necessary, when determining the actual file path to pass to the
+.Xr identify 1
+command.
+Otherwise,
+.Cm src
+is appended to
+.Dq . .
+.It
+.Va incdir\-footer\-permalink\-text .
If set, and the variable
-.B incdir-only-summary
-is set to \[lq]1\[rq], when the file where this variable is set is included by
-the \fC{incdir}\fR directive, \fC<footer>\fR tag containing the permalink to the
-calling file will be appended to the text between the summary marks \fC/-\fR and
-\fC-/\fR.
-.
-.IP \[bu]
-.BR incdir-only-summary .
-If set to \[lq]1\[rq], when the file where this variable is set is included by
-the \fC{incdir}\fR directive, only the text within the summary marks \fC/-\fR
-and \fC-/\fR will be output.
-.
-.IP \[bu]
-.BR inline-stylesheet .
-The contents of this variable will be treated as a
-.SM CSS
-file name to be included inline in the header using the \fC<style>\fR tag. You
-can add more than one
-.I inline-stylesheet
-declaration per
-.I .slw
+.Va incdir\-only\-summary
+is set to
+.Dq 1 ,
+when the file where this variable is set is included by the
+.Ql {incdir}
+directive,
+.Ql <footer>
+tag containing the permalink to the calling file will be appended to the text
+between the summary marks
+.Ql /-
+and
+.Ql -/ .
+.It
+.Va incdir\-only\-summary .
+If set to
+.Dq 1 ,
+when the file where this variable is set is included by the
+.Ql {incdir}
+directive, only the text within the summary marks
+.Ql /-
+and
+.Ql -/
+will be output.
+.It
+.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
+declaration per
+.Pa .slw
file.
-.
-.IP \[bu]
-.BR lang .
-Contents of this variable will be used for the \fClang\fR attribute of the
-\fC<html>\fR tag.
-.
-.IP \[bu]
-.BR link-prefix .
+.It
+.Va lang .
+Contents of this variable will be used for the
+.Cm lang
+attribute of the
+.Ql <html>
+tag.
+.It
+.Va link\-prefix .
This variable specifies the prefix which will be prepended to relative URLs in
-links. Final slash needs to be included if
-.B link-prefix
+links.
+Final slash needs to be included if
+.Va link\-prefix
is a complete path.
-.
-.IP \[bu]
-.BR meta .
+.It
+.Va meta .
Contents of this variable is treated as a filename specifying the TSV file
-containing a list of values to be inserted into meta tags. The first row of this
-TSV file is treated as the header row and ignored. First column in this TSV file
-contains the meta variable names, and the second column contains meta variable
-values. For each row, a \fC<meta name="\f[CI]firstcol\fC"
-content="\f[CI]secondcol\f[CR]">\fR is inserted, where
-.I firstcol
+containing a list of values to be inserted into meta tags.
+The first row of this TSV file is treated as the header row and ignored.
+First column in this TSV file contains the meta variable names, and the second
+column contains meta variable values.
+For each row, a
+.Ql <meta name=\(dq Ns Ar firstcol Ns \(dq content=\(dq Ns Ar secondcol Ns \(dq>
+is inserted, where
+.Ar firstcol
is the first column, and
-.I secondcol
-is the second column. If the values in the second column are surrounded with
-percent signs (\fC%\fR), the value between them is treated as the name of the
-YAML variable to insert. For example, having the file
-.IR m.tsv :
-.
-.CDS 8
+.Ar secondcol
+is the second column.
+If the values in the second column are surrounded with percent signs
+.Pf "(" Ns Ql % Ns
+), the value between them is treated as the name of the
+YAML variable to insert.
+For example, having the file
+.Pa m.tsv :
+.Bd -literal -offset Ds
Name Content
og:url %canonical%
-.CDE
-.
-.IP ""
+.Ed
+.Pp
and
-.
-.CDS 8
+.Bd -literal -offset Ds
---
canonical: https://example.com/
meta: m.tsv
---
-.CDE
-.
-.IP ""
+.Ed
+.Pp
in the
-.I .slw
+.Pa .slw
file, a
-.
-.CDS 8
+.Bd -literal -offset Ds
<meta name="og:url" content="https://example.com/">
-.CDE
-.
-.IP ""
+.Ed
+.Pp
line will be added to the output.
-.
-.IP \[bu]
-.BR permalink-url .
-If present, this
-.SM URL
-will completely replace the link used in the
-.I href
+.It
+.Va permalink\-url .
+If present, this URL will completely replace the link used in the
+.Cm href
attribute of permalinks generated by the
-.I incdir
-directive. This variable is more useful in individual
-.I .slw
+.Ic incdir
+directive.
+This variable is more useful in individual
+.Pa .slw
files inside the subdirectories of the
-.I dirname
+.Ar dirname
provided to the
-.I incdir
+.Ic incdir
directive.
-.
-.IP \[bu]
-.BR site-desc .
+.It
+.Va site\-desc .
The contents of this variable will be inserted as the value of the
-.I content
-attribute of the \fC<meta name="description">\fR tag.
-.
-.IP \[bu]
-.BR site-name .
-The contents of this variable will be inserted inside the \fC<title></title>\fR
+.Cm content
+attribute of the
+.Ql <meta name="description">
+tag.
+.It
+.Va site\-name .
+The contents of this variable will be inserted inside the
+.Ql <title></title>
tags.
-.
-.IP \[bu]
-.BR stylesheet .
-The contents of this variable will be treated as a
-.SM CSS
-file name to be included using the \fC<link rel="stylesheet">\fR tag. You can
-add more than one
-.I stylesheet
-declaration per
-.I .slw
+.It
+.Va stylesheet .
+The contents of this variable will be treated as a CSS file name to be included
+using the
+.Ql <link rel="stylesheet">
+tag.
+You can add more than one
+.Va stylesheet
+declaration per
+.Pa .slw
file.
-.
-.IP \[bu]
-.BR title .
+.It
+.Va title .
If present, contents of this variable will be prepended to the body (inside a
-\fC<header>\fR tag if it is set) as a heading with the level determined by the
-.I title-heading-level
-variable, defaulting
-to 2. (\fCtitle: Some title\fR becomes \fC<h2>Some title</h2>\fR).
-.
-.IP \[bu]
-.BR title-heading-level .
+.Ql <header>
+tag if it is set) as a heading with the level determined by the
+.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 .
See
-.BR title .
-.
-.SS Special macros
+.Sx title .
+.El
.
-.IP \[bu] 4
-.BR permalink .
+.Ss "Special macros"
+.Bl -bullet -width 1m
+.It
+.Ic permalink .
If present, the body of this macro will be inserted into permalinks generated by
the
-.I incdir
-directive, similar to the macro-form of links.
-.
-.SH "SEE ALSO"
-.BR sed (1)
-.
-.SH EXAMPLES
-.
-.LP
-Given the file \fCindex.slw\fR in the current directory:
-.CDS 4
+.Ic incdir
+directive, similar to the macro\-form of links.
+.El
+.
+.Sh EXAMPLES
+Given the file
+.Pa index.slw
+in the current directory:
+.Bd -literal -offset Ds
---
site-name: Test website
site-desc: My first website in slweb
@@ -1183,13 +1286,14 @@ site-desc: My first website in slweb
This is an _example_ of a statically generated HTML.
{/main}
-.CDE
+.Ed
+.Pp
after using the command:
-.CDS 4
-$ slweb index.slw > index.html
-.CDE
-file \fCindex.html\fR contains:
-.CDS 4
+.Dl $ slweb index.slw > index.html
+file
+.Pa index.html
+contains:
+.Bd -literal -offset Ds
<!DOCTYPE html>
<html lang="en">
<head>
@@ -1204,66 +1308,77 @@ file \fCindex.html\fR contains:
<main>
<h1>Hello world</h1>
-<p>This is an <em>example</em> of a statically generated HTML.</p>
+<p>This is an <em>example</em> of a statically generated HTML.
</main>
</body>
</html>
-.CDE
+.Ed
.
-.SH "KNOWN LIMITATIONS"
+.Sh "SEE ALSO"
+.Xr sed 1
.
-.IP \[bu] 4
-Currently there is no way to determine where the paragraph inside a tag should
-begin and end without adding blank lines or using the \fC{p}{/p}\fR notation.
-For example, the code
+.Sh AUTHORS
+.An "Strahinya Radich" Aq contact@strahinja.org ,
+2020\-2024
.
-.CDS 8
+.Sh BUGS
+Bugs can be reported using the ticket tracker at:
+.Lk https://\:todo.sr.ht/\:~strahinja/\:slweb
+.
+.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"
+and the change of behavior of
+.Nm
+to not output ending
+.Ql </p>
+tags, without adding blank lines or using the
+.Ql {p}{/p}
+notation,
+.Ql <p></p>
+tags in the output would be intertwined together with other tags.
+For example, the code
+.Bd -literal -offset Ds
{tag}
First paragraph
Second paragraph
{/tag}
-.CDE
-.
-.IP
-will produce
-.
-.CDS 8
+.Ed
+.Pp
+would produce
+.Bd -literal -offset Ds
<tag>
First paragraph
<p>Second paragraph
</tag></p>
-.CDE
-.
-.IP
-You can suppress the paragraph starting/ending tags by prepending blank lines
+.Ed
+.Pp
+One could suppress the paragraph starting/ending tags by prepending blank lines
with a backslash, like this:
-.
-.CDS 8
+.Bd -literal -offset Ds
{tag}
First paragraph
-\[rs]
+\e
Second paragraph
{/tag}
-.CDE
-.
-.IP
-which will produce
-.
-.CDS 8
+.Ed
+.Pp
+which would produce
+.Bd -literal -offset Ds
<tag>
First paragraph
Second paragraph
</tag>
-.CDE
-.
-.IP
-Adding blank lines helps, if paragraphs are desired:
-.
-.CDS 8
+.Ed
+.Pp
+Adding blank lines was another option if paragraphs were desired:
+.Bd -literal -offset Ds
{tag}
First paragraph
@@ -1271,33 +1386,13 @@ First paragraph
Second paragraph
{/tag}
-.CDE
-.
-.IP
-will produce
-.
-.CDS 8
+.Ed
+.Pp
+would produce
+.Bd -literal -offset Ds
<tag>
<p>First paragraph</p>
<p>Second paragraph</p>
</tag>
-.CDE
-.
-.IP
-Also see
-.B Break marks
-above.
-.
-.SH AUTHOR
-.
-Strahinya Radich,
-.UR https://\:strahinja.org
-.UE
-.
-.SH BUGS
-.
-.LP
-Bugs can be reported using the ticket tracker at:
-.UR https://\:todo.sr.ht/\:~strahinja/\:slweb
-.UE
+.Ed
