Mercurial > paster

.\"
.\" Copyright (c) 2020-2022 David Demelier <markand@malikania.fr>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd 25 November, 2020
.Dt PASTERD-THEMES 5
.Os
.\" NAME
.Sh NAME
.Nm pasterd-themes
.Nd themes for pasterd
.\" DESCRIPTION
.Sh DESCRIPTION
This manual page describes the file hierarchy and syntax required to create a
new theme for
.Nm pasterd .
.Pp
A theme consists of fragments and pages. A fragment is a piece of HTML code that
may be repeated while a page is usually the HTML code that is inside the
.Dq <body></body>
HTML tag.
.\" THEME STRUCTURE
.Sh THEME STRUCTURE
The easiest way to create a new theme is to copy the predefined
.Pa minimal
theme and adapt the files to the desired style. See it in
@SHAREDIR@/paster/themes/minimal.
.Pp
The following files must be provided into a directory:
.Bd -literal -offset indent
theme/fragments/duration.html
theme/fragments/language.html
theme/fragments/footer.html
theme/fragments/header.html
theme/fragments/paste.html
theme/pages/400.html
theme/pages/404.html
theme/pages/500.html
theme/pages/paste.html
theme/pages/index.html
theme/pages/new.html
theme/pages/search.html
.Ed
.Pp
A special
.Pa static
directory into the theme can be used to provide non templates data such as
images, Javascript and CSS files. They are not processed and provided as-is.
.Pp
See below for a description per file.
.\" KEYWORDS
.Sh KEYWORDS
Templates files may contain keywords that are replaced during processing using
the syntax
.Dq @@variable@@ .
.Pp
The following keywords are supported:
.Bl -tag -width 10n
.It Va author
The paste author.
.It Va date
Date as a string.
.It Va duration
Duration expressed as a string. May be
.Dq hour ,
.Dq day ,
.Dq week ,
.Dq month .
.It Va durations
Fragment repeated for every duration supported using
.Pa fragments/duration.html
template.
.It Va language
The paste language type.
.It Va languages
Fragment repeated for every language supported using
.Pa fragments/language.html
template.
.It Va expiration
The time left for the paste expressed as minutes, hours or days depending on the
time left.
.It Va id
Unique paste indentifier.
.It Va pastes
Fragment repeated for every paste using
.Pa fragments/paste.html
template.
.It Va public
String set to
.Dq Yes
if public or
.Dq \&No
otherwise.
.It Va title
When used within header fragment, page's title otherwise paste's title.
.El
.\" PAGES AND FRAGMENTS
.Sh PAGES AND FRAGMENTS
.\" fragments/duration.html
.Ss fragments/duration.html
A fragment that should generate a
.Dq <select>
option for the given duration.
.Pp
Supported keywords:
.Bl -bullet -compact
.It
.Va duration
.El
.\" fragments/footer.html
.Ss fragments/footer.html
Fragment applied at the end of a page.
.\" fragments/header.html
.Ss fragments/header.html
Fragment applied at the beginning of a page.
.Pp
Supported keywords:
.Bl -bullet -compact
.It
.Va title
.El
.\" fragments/language.html
.Ss fragments/language.html
A fragment that should generate a
.Dq <select>
option for the given language.
.Pp
Supported keywords:
.Bl -bullet -compact
.It
.Va language
.El
.\" fragments/paste.html
.Ss fragments/paste.html
Repeated fragment in the
.Pa pages/index.html
page.
.Pp
Supported keywords:
.Bl -bullet -compact
.It
.Va id
.It
.Va title
.It
.Va author
.It
.Va date
.It
.Va expiration
.It
.Va language
.El
.Ss pages/400.html
.Ss pages/404.html
.Ss pages/500.html
Those pages are used to indicate an error that are generated from
.Nm pasterd .
.\" pages/index.html
.Ss pages/index.html
This page is the landing of the
.Nm pasterd
program. It should provide a list of last recents paste.
.Pp
Supported keywords:
.Bl -bullet -compact
.It
.Va pastes
.El
.\" pages/paste.html
.Ss pages/paste.html
Details of a paste.
.Pp
Supported keywords:
.Bl -bullet -compact
.It
.Va author
.It
.Va code
.It
.Va date
.It
.Va expiration
.It
.Va id
.It
.Va public
.It
.Va title
.El
.\" pages/new.html
.Ss pages/new.html
Create a form for sending a new paste. The form should submit a POST request to
the same page with the following field data:
.Pp
.Bl -tag -width 10n
.It Va author
Paste author.
.It Va code
The code content.
.It Va duration
Paste duration (should use
.Dq durations
keyword).
.It Va language
The code language (should use
.Dq languages
keyword).
.It Va title
Paste title.
.El
.Pp
Supported keywords:
.Bl -bullet -compact
.It
.Va durations
.It
.Va languages
.El
.\" pages/search.html
.Ss pages/search.html
Create a form for searching pastes. The form should submit a POST request to
the same page with the following field data:
.Bl -tag
.It Va author
Author of paste.
.It Va language
Paste language.
.It Va title
Title to search
.El
.\" SEE ALSO
.Sh SEE ALSO
.Xr pasterd 8
author	David Demelier <markand@malikania.fr>
date	Wed, 29 Jun 2022 20:47:24 +0200
parents	1a6abb3ed16a
children	1a98bc0daa49