aerc-stylesets

package: aerc

title: aerc-stylesets(7)

text:
# aerc-stylesets(7)

## NAME
aerc-stylesets - styleset file specification for aerc(1)

## SYNOPSIS
aerc uses a simple configuration syntax to configure the styleset for its ui.

## STYLESET CONFIGURATION
The styleset is described as <object>.<attribute> = <value> pairs.

For example, in the line below, the foreground color of the style object msglist_unread is set to cornflowerblue

msglist_unread.fg = cornflowerblue

The configuration also allows wildcard matching of the keys to configure multiple style objects at a time.

## ATTRIBUTES
The following options are available to be modified for each of the style objects.

<object>.fg = <color>

The foreground color of the style object is set.

<object>.bg = <color>

The background color of the style object is set.

<object>.bold = true|false|toggle

The bold attribute of the style object is set/unset.

<object>.blink = true|false|toggle

The blink attribute of the style object is set/unset. The terminal needs to support blinking text.

<object>.underline = true|false|toggle

The underline attribute of the style object is set/unset. The terminal needs to support underline text.

<object>.italic = true|false|toggle

The italic attribute of the style object is set/unset. The terminal needs to support italic text.

<object>.dim = true|false|toggle

The dim attribute of the style object is set/unset. The terminal needs to support half-bright text.

<object>.reverse = true|false|toggle

Reverses the color of the style object. Exchanges the foreground and background colors. If the value is false, it doesn't change anything.

<object>.normal = true

All the attributes of the style object are unset. The value doesn't matter.

<object>.default = true

Set the style object to the default style of the context. Usually based on the terminal. The value doesn't matter.

## STYLE OBJECTS
The style objects represent the various ui elements or ui instances for styling.

Style Object

Description

default

The default style object used for normal ui elements while not using specialized configuration.

error

The style used to show errors.

warning

The style used when showing warnings.

success

The style used for success messages.

title

The style object used to style titles in ui elements.

header

The style object used to style headers in ui elements.

statusline_default

The default style applied to the statusline.

statusline_error

The style used for error messages in statusline.

statusline_success

The style used for success messages in statusline.

msglist_default

The default style for messages in a message list.

msglist_unread

Unread messages in a message list.

msglist_read

Read messages in a message list.

msglist_flagged

The messages with the flagged flag.

msglist_deleted

The messages marked as deleted.

msglist_marked

The messages with the marked flag.

msglist_result

The messages which match the current search.

msglist_answered

The messages marked as answered.

dirlist_default

The default style for directories in the directory list.

dirlist_unread

The style used for directories with unread messages

dirlist_recent

The style used for directories with recent messages

completion_default

The default style for the completion engine.

completion_gutter

The completion gutter.

completion_pill

The completion pill.

tab

The style for the tab bar.

stack

The style for ui stack element.

spinner

The style for the loading spinner.

border

The style used to draw borders (only the bg color is used unless you customize border-char-vertical and/or border-char-horizontal in aerc.conf).

selector_default

The default style for the selector ui element.

selector_focused

The focused item in a selector ui element.

selector_chooser

The item chooser in a selector ui element.

These next style objects only affect the built-in colorize filter and must be declared under a [viewer] section of the styleset file.

Style Object

Description

url

URLs.

header

RFC-822-like header names.

signature

Email signatures.

diff_meta

Patch diff meta lines.

diff_chunk

Patch diff chunks.

diff_add

Patch diff added lines.

diff_del

Patch diff deleted lines.

quote_1

First level quoted text.

quote_2

Second level quoted text.

quote_3

Third level quoted text.

quote_4

Fourth level quoted text.

quote_x

Above fourth level quoted text.

User defined styles can be used to style arbitrary strings in go-templates (see .Style in aerc-templates(7)). User styles must be defined in the [user] ini section. Styles can be referenced by their name (e.g. red.fg is named "red").

Example:

```
[user]
red.fg=red
```

User styles are layered with other styles applied to the context in which they are rendered. The user style colors (fg and/or bg) will only be effective if the context style does not define any. Other boolean attributes will be merged with the underlying style boolean attributes.

For example, if the context style is:

fg=red bold

And the inline style is:

fg=yellow italic underline

The effective style will be:

fg=red bold italic underline

## FNMATCH STYLE WILDCARD MATCHING
The styleset configuration can be made simpler by using the fnmatch style wildcard matching for the style object.

The special characters used in the fnmatch wildcards are:

Pattern

Meaning

*

Matches everything

?

Matches any single character

For example, the following wildcards can be made using this syntax.

Example

Description

*.fg = blue

Set the foreground color of all style objects to blue.

*list.bg = hotpink

Set the background color of all style objects that end in list to hotpink.

Note that the statements in a given styleset are parsed in the order in which they are written. That means that with the following styleset:

```
msglist_marked.fg = pink
msglist_*.fg = white
```

The msglist_marked.fg attribute will be set to white.

## SELECTED MODIFIER
The selected modifier can be applied to any style object. The style provided for the selected modifier is applied on top of the style object it corresponds to.

If you would like to make sure message that are flagged as read in the msglist appear in yellow foreground and black background. You can specify that with this:

msglist_default.selected.fg = yellow msglist_default.selected.bg = black

If we specify the global style selected modifier using fnmatch as below:

*.selected.reverse = toggle

This toggles the reverse switch for selected version of all the style objects.

selected objects inherit from all attributes of their non-selected counterparts. selected statements are parsed after non-selected ones and effectively override the attributes of the non-selected style object.

## LAYERED STYLES
Some styles, (currently the msglist_* and dirlist_* ones) are applied in layers. If a style differs from the base (in this case *list_default) then that style applies, unless overridden by a higher layer. If fg and bg colors are not defined explicitly (or defined to the default color) they will be considered as "transparent" and the colors from the lower layer will be used instead.

The order that msglist_* styles are applied in is, from first to last:

1.msglist_default

2.msglist_unread

3.msglist_read

4.msglist_answered

5.msglist_flagged

6.msglist_deleted

7.msglist_result

8.msglist_marked

So, the marked style will override all other msglist styles.

The order for dirlist_* styles is:

1.dirlist_default

2.dirlist_unread

3.dirlist_recent

## DYNAMIC MESSAGE LIST STYLES
All msglist_* styles can be defined for specific email header values. The syntax is as follows:

msglist_<name>.<header>,<header_value>.<attribute> = <attr_value>

If <header_value> starts with a tilde character ~, it will be interpreted as a regular expression.

Examples:

```
msglist*.X-Sourcehut-Patchset-Update,APPROVED.fg = green
msglist*.X-Sourcehut-Patchset-Update,NEEDS_REVISION.fg = yellow
msglist*.X-Sourcehut-Patchset-Update,REJECTED.fg = red
"msglist_*.Subject,~^([[w-]+]s*)?[(RFC )?PATCH.fg" = #ffffaf
"msglist_*.Subject,~^([[w-]+]s*)?[(RFC )?PATCH.selected.fg" = #ffffaf
```

When a dynamic style is matched to an email header, it will be used in priority compared to its non-dynamic counterpart. Provided the following styleset:

```
msglist_marked.fg = blue
msglist_*.Subject,~foobar.fg = red
```

An email with foobar it its subject will be colored in red all the time, since msglist_* also applies to msglist_marked.

## COLORS
The color values are set using the values accepted by the tcell library. The values can be one of the following.

default

The color is set as per the system or terminal default.

<Color name>

Any w3c approved color name is used to set colors for the style.

<Hex code>

Hexcode for a color can be used. The format must be #XXXXXX.

<Dec number>

Color based on the terminal palette index. Valid numbers are between 0 and 255.

## SEE ALSO
aerc(1) aerc-config(5)

## AUTHORS
Originally created by Drew DeVault <sir@cmpwn.com> and maintained by Robin Jarry <robin@jarry.cc> who is assisted by other open source contributors. For more information about aerc development, see https://sr.ht/~rjarry/aerc/.


aerc-templates

title: aerc-templates(7)

text:
# aerc-templates(7)

## NAME
aerc-templates - template file specification for aerc(1)

## SYNOPSIS
aerc uses the go text/template package for the template parsing. Refer to the go text/template documentation for the general syntax. The template syntax described below can be used for message template files and for dynamic formatting of some UI widgets.

Template files are composed of headers, followed by a newline, followed by the body text.

Example:

```
X-Clacks-Overhead: GNU Terry Pratchett
Hello,
Greetings,
Chuck
```

If you have a template that doesn't add any header, it must be preceded by a newline, to avoid parsing parts of the body as header text.

All headers defined in the template will have precedence over any headers that are initialized by aerc (e.g. Subject, To, From, Cc) when composing a new message, forwarding or replying.

## MESSAGE DATA
The following data can be used in templates. Though they are not all available always.

Addresses

An array of mail.Address. That can be used to add sender or recipient names to the template.

•{{.From}}: List of senders.

•{{.Peer}}: List of senders or To recipients if the message is from you.

•{{.To}}: List of To recipients. Not always Available.

•{{.ReplyTo}}: List of ReplyTo recipients. Not always Available.

•{{.Cc}}: List of Cc recipients. Not always Available.

•{{.Bcc}}: List of Cc recipients. Not always Available.

•{{.OriginalFrom}}: List of senders of the original message. Available for quoted reply and forward.

Example:

Get the name of the first sender.

```
{{(index .From 0).Name}}
{{index (.From | names) 0}}
```

Get the email address of the first sender.

```
{{(index .From 0).Address}}
```

Date and Time

The date and time information is always available and can be easily formatted.

•{{.Date}}: Date and time information when the compose window is opened.

•{{.OriginalDate}}: Date and time when the original message of received. Available for quoted reply and forward.

To format the date fields, dateFormat and .Local are provided. Refer to the TEMPLATE FUNCTIONS section for details.

Subject

The subject of the email (ThreadPrefix will be empty unless threading is enabled).

```
{{.ThreadPrefix}}{{.Subject}}
```

The subject of the email stripped of any Re: and Fwd: prefixes.

```
{{.SubjectBase}}
```

Flags

List of message flags, not available when composing, replying nor forwarding. This is a list of strings that may be converted to a single string with join.

```
{{.Flags | join ""}}
```

Labels

Message labels (for example notmuch tags). Not available when composing, replying nor forwarding. This is a list of strings that may be converted to a single string with join.

```
{{.Labels | join " "}}
```

Size

The size of the message in bytes. Not available when composing, replying nor forwarding. It can be formatted with humanReadable.

```
{{.Size | humanReadable}}
```

Any header value

Any header value of the email.

```
{{.Header "x-foo-bar"}}
```

Any header values of the original forwared or replied message:

```
{{.OriginalHeader "x-foo-bar"}}
```

MIME Type

MIME Type is available for quoted reply and forward.

•{{.OriginalMIMEType}}: MIME type info of quoted mail part. Usually text/plain or text/html.

Original Message

When using quoted reply or forward, the original message is available in a field called OriginalText.

```
{{.OriginalText}}
```

Account info

The current account name:

```
{{.Account}}
```

Currently selected mailbox folder:

```
{{.Folder}}
```

Current message counts for all folders:

```
{{.Recent}} {{.Unread}} {{.Exists}}
{{.RUE}}
```

IANA role of the mailbox, converted to lowercase. aerc uses one custom role: 'query', which is given to mailboxes from a notmuch query-map

```
{{if eq .Role "query"}}{{...}}{{else}}{{...}}{{end}}
```

Current message counts for specific folders:

```
{{.Recent "inbox"}}
{{.Unread "inbox" "aerc/pending"}}
{{.Exists "archive" "spam" "foo/baz" "foo/bar"}}
{{.RUE "inbox"}}
```

Status line

The following data will only be available in the status line templates: Connection state.

```
{{.Connected}}
{{.ConnectionInfo}}
```

General status information (e.g. filter, search) separated with [statusline].separator.

```
{{.ContentInfo}}
```

Combination of {{.ConnectionInfo}} and {{.StatusInfo}} separated with [statusline].separator.

```
{{.StatusInfo}}
```

General on/off information (e.g. passthrough, threading, sorting), separated with [statusline].separator.

```
{{.TrayInfo}}
```

Currently pressed key sequence that does not match any key binding and/or is incomplete.

```
{{.PendingKeys}}
```

## TEMPLATE FUNCTIONS
Besides the standard functions described in go's text/template documentation, aerc provides the following additional functions:

wrap

Wrap the original text to the specified number of characters per line.

```
{{wrap 72 .OriginalText}}
```

quote

Prepends each line with "> ".

```
{{quote .OriginalText}}
```

trimSignature

Removes the signature froma passed in mail. Quoted signatures are kept as they are.

```
{{trimSignature .OriginalText}}
```

join

Join the provided list of strings with a separator:

```
{{.To | names | join ", "}}
```

names

Extracts the names part from a mail.Address list. If there is no name available, the mbox (email address without @domain) is returned instead.

```
{{.To | names | join ", "}}
{{index (.To | names) 0}}
```

firstnames

Extracts the first names part from a mail.Address list. If there is no name available, the short mbox (start of email address without @domain) is returned instead.

```
{{.To | firstnames | join ", "}}
{{index (.To | firstnames) 0}}
```

initials

Extracts the initials from the names part from a mail.Address list. If there is no name available, the first letter of the email address is returned instead.

```
{{.To | initials | join ", "}}
{{index (.To | initials) 0}}
```

emails

Extracts the addresses part from a mail.Address list.

```
{{.To | emails | join ", "}}
{{index (.To | emails) 0}}
```

mboxes

Extracts the mbox part from a mail.Address list (i.e. smith from smith@example.com).

```
{{.To | mboxes | join ", "}}
{{index (.To | mboxes) 0}}
```

shortmboxes

Extracts the short mbox part from a mail.Address list (i.e. smith from smith.and.wesson@example.com).

```
{{.To | shortmboxes | join ", "}}
{{index (.To | shortmboxes) 0}}
```

persons

Formats a list of mail.Address into a list of strings containing the human readable form of RFC5322 (e.g. Firstname Lastname <email@address.tld>).

```
{{.To | persons | join ", "}}
{{index (.To | persons) 0}}
```

exec

Execute external command, provide the second argument to its stdin.

```
{{exec `/usr/libexec/aerc/filters/html` .OriginalText}}
```

.Local

Convert the date to the local timezone as specified by the locale.

```
{{.Date.Local}}
```

dateFormat

Format date and time according to the format passed as the second argument. The format must be specified according to go's time package format.

```
{{dateFormat .Date "Mon Jan 2 15:04:05 -0700 MST 2006"}}
```

You can also use the .DateAutoFormat method to format the date according to *-time*format settings:

```
{{.DateAutoFormat .OriginalDate.Local}}
```

now

Return the current date as a golang time.Time object that can be formated with dateFormat.

```
{{dateFormat now "Mon Jan 2 15:04:05 -0700 MST 2006"}}
```

humanReadable

Return the human readable form of an integer value.

```
{{humanReadable 3217653721}}
```

cwd

Return the current working directory with the user home dir replaced by ~.

```
{{cwd}}
```

compactDir

Reduce a directory path into a compact form. The directory name will be split with / and each part will be reduced to the first letter in its name: INBOX/01_WORK/PROJECT will become I/W/PROJECT.

```
{{compactPath .Folder}}
```

.Style

Apply a user-defined style (see aerc-stylesets(7)) to a string.

```
{{.Style .Account "red"}}
{{.Style .ThreadPrefix "thread"}}{{.Subject}}
```

.StyleSwitch

Apply a user-defined style (see aerc-stylesets(7)) to a string if it matches one of the associated regular expressions. If the string does not match any of the expressions, leave it unstyled.

```
{{.StyleSwitch .Subject (`^([[w-]+]s*)?[(RFC )?PATCH` "cyan")}}
{{.StyleSwitch (.From | names | join ", ") (case `Tim` "cyan") (case `Robin` "pink-blink") (default "blue")}}
```

version

Returns the version of aerc, which can be useful for things like X-Mailer.

```
X-Mailer: aerc {{version}}
```

match

Check if a string matches a regular expression. This is intended for use in conditional control flow:

```
{{if match .Folder `.*/Archive-[0-9]+`}}{{humanReadable .Unread}}{{end}}
```

switch

Do swich/case/default control flows. The switch value is compared with regular expressions. If none of the case/default arms match, an empty string is returned.

```
{{switch .Folder (case `^INBOX$` "📥") (case `^Archive/.*` "🗃") (default "📁")}}
```

Function chaining

All of the template functions can be chained together if needed. Example: Automatic HTML parsing for text/html mime type messages

```
{{if eq .OriginalMIMEType "text/html"}}
{{exec `/usr/libexec/aerc/filters/html` .OriginalText | wrap 72 | quote}}
{{else}}
{{wrap 72 .OriginalText | trimSignature | quote}}
{{end}}
```

## SEE ALSO
aerc(1) aerc-config(5)

## AUTHORS
Originally created by Drew DeVault <sir@cmpwn.com> and maintained by Robin Jarry <robin@jarry.cc> who is assisted by other open source contributors. For more information about aerc development, see https://sr.ht/~rjarry/aerc/.


aerc-tutorial

title: aerc-tutorial(7)

text:
# aerc-tutorial(7)

## NAME
aerc-tutorial - tutorial for aerc(1)

## INTRODUCTION
Welcome to aerc! This tutorial will guide you through your first steps in using the client. This tutorial is a man page - you can read it again later with :help tutorial from aerc, or man aerc-tutorial from your terminal.

First, let's introduce some basic keybindings. For convention, we'll use <C-p> to represent Ctrl+p, which matches the convention used for writing keybindings for aerc.

<C-p>, <C-n>

Cycles to the previous or next tab

Try using these now to switch between your message list and the tutorial. In your message list, we use vim-style keys to get around.

k, j

Scrolls up and down between messages

<C-u>, <C-d>

Scrolls half a page up or down

g, G

Selects the first or last message, respectively

K, J

Switches between folders in the sidebar

<Enter>

Opens the selected message

You can also search the selected folder with /, or filter with \ . When searching you can use n and p to jump to the next and previous result. Filtering hides any non-matching message.

## THE MESSAGE VIEWER
Press <Enter> to open a message. By default, the message viewer will display your message using less(1). This should also have familiar, vim-like keybindings for scrolling around in your message.

Multipart messages (messages with attachments, or messages with several alternative formats) show a part selector on the bottom of the message viewer.

<C-k>, <C-j>

Cycle between parts of a multipart message

q

Close the message viewer

To show HTML messages, uncomment the text/html filter in your aerc.conf file (which is probably in ~/.config/aerc/) and install its dependencies: w3m and dante-utils.

You can also do many tasks you could do in the message list from here, like replying to emails, deleting the email, or view the next and previous message (J and K).

## COMPOSING MESSAGES
Return to the message list by pressing q to dismiss the message viewer. Once there, let's compose a message.

C

Compose a new message

rr

Reply-all to a message

rq

Reply-all to a message, and pre-fill the editor with a quoted version of the message being replied to

Rr

Reply to a message

Rq

Reply to a message, and pre-fill the editor with a quoted version of the message being replied to

For now, let's use C to compose a new message. The message composer will appear. You should see To, From, and Subject lines, as well as your $EDITOR. You can use <Tab> or <C-j> and <C-k> to cycle between these fields (tab won't cycle between fields once you enter the editor, but <C-j> and <C-k> will).

Let's send an email to yourself. Note that the To and From headers expect RFC 5322 addresses, e.g. John Doe <john@example.org>, or simply <john@example.org>. Separate multiple recipients with commas. Go ahead and fill out an email, then close the editor.

The message review screen is shown next. You have a chance now to revise the email before it's sent. Press y to send the email if it looks good.

Note: when using the terminal in the message view, you can summon aerc's ex command line by using <C-x>. : is sent to the editor.

## USING THE TERMINAL
aerc comes with an embedded terminal, which you've already used to view and edit emails. We can also use this for other purposes, such as referencing a git repository while reviewing a patch. From the message list, we can use the following keybindings to open a terminal:

<C-t>

Opens a new terminal tab, running your shell

$, !

Prompts for a command to run, then opens a new terminal tab running that command

|

Prompts for a command to run, then pipes the selected email into that command and displays the result on a new terminal tab

Try pressing $ and entering top. You can also use the :cd command to change aerc's working directory, and the directory in which new terminals run. Use :pwd to see it again if you're not sure where you are.

## ADDITIONAL NOTES

### COMMANDS
Every keybinding is ultimately bound to an aerc command. You can also summon the command line by pressing :, then entering one of these commands. See aerc(1) or :help for a full list of commands.

### MESSAGE FILTERS
When displaying messages in the message viewer, aerc will pipe them through a message filter first. This allows you to decode messages in non-plaintext formats, add syntax highlighting, etc. aerc ships with a few default filters:

•text/plain parts are piped through the colorized built-in filter which handles URL, quotes and diff coloring.

•text/calendar is processed to be human readable text

•text/html (disabled by default) can be uncommented to pipe through the built-in html filter.

### CUSTOMIZING AERC
Aerc is highly customizable. Review aerc-config(5) (or use :help config) to learn more about how to add custom keybindings, install new message filters, change its appearance and behavior, and so on.

## AUTHORS
Originally created by Drew DeVault <sir@cmpwn.com> and maintained by Robin Jarry <robin@jarry.cc> who is assisted by other open source contributors. For more information about aerc development, see https://sr.ht/~rjarry/aerc/.


package: alsa-utils

title: alsactl_init(7)

summary: alsa control management \- initialization

text:
# alsactl_init(7)

## NAME
alsactl_init - alsa control management - initialization

## DESCRIPTION
"alsactl init" provides soundcard specific initialization.

## CONFIGURATION
All "alsactl init" configuration files are placed in /usr/share/alsa/init/ directory. The top level configuration file is /usr/share/alsa/init/00main. The default top-level file can be also specified using -i or --initfile parameter for the alsactl tool. Every file consists of a set of lines of text. All empty lines or lines beginning with '#' will be ignored.

### Rules files
The "alsactl init" rules are read from the files located in the /usr/share/alsa/init/*. The top level configuration file is /usr/share/alsa/init/00main. Every line in the rules file contains at least one key value pair. There are two kind of keys, match and assignment keys. If all match keys are matching against its value, the rule gets applied and the assign keys get the specified value assigned.

A rule may consists of a list of one or more key value pairs separated by a comma. Each key has a distinct operation, depending on the used operator. Valid operators are:

==

Compare for equality.

!=

Compare for non-equality.

=

Assign a value to a key. Keys that represent a list, are reset and only this single value is assigned.

+=

Add the value to a key that holds a list of entries.

:=

Assign a value to a key finally; disallow any later changes, which may be used to prevent changes by any later rules.

The following key names can be used to match against device properties:

CARDINDEX

Match the card index of the ALSA driver.

CTL{attribute}

Set or test universal control attribute. Possible attributes: numid

Numeric control identification.

iface, interface

Control interface name (CARD, HWEDEP, MIXER, PCM, RAWMIDI, TIMER, SEQUENCER)

subdev, subdevice

Subdevice number.

name

Control name

index

Control index

type

Control type (BOOLEAN, INTEGER, INTEGER64, ENUMERATED, BYTES, IEC958)

attr, attribute

Attributes (stored in a string - use match characters * and ?): r

control is readable

w

control is writable

v

control is volatile

i

control is inactive

l

control is locked

R

control is TLV readable

W

control is TLV writable

C

control is TLV commandable

o

process is owner of this control

u

control created in user space

owner

Control owner process PID number

count

Control count of values

min

Value range - minimum value

max

Value range - maximum value

step

Value range - step value

dBmin

Value range - minimum dB value

dBmax

Value range - maximum dB value

items

Enumerated value - number of text items

enums

Enumerated value - list of text names stored between '|' character

value

Value of control stored to a string delimited by comma (,).

do_search

Search for a control. Value "1" is returned if a control was found. The CTL{name} key might contain match characters * and ?. An control index might be specified as first argument starting from zero (e.g. CTL{do_search 2}="1").

do_count

Search for a controls and return total count of matched ones. The CTL{name} key might contain match characters * and ?.

CONFIG{sysfs_device}

The relative path to sysfs subsystem specifying the root directory of a soundcard device. Usually, it should be set to "/class/sound/card$cardinfo{card}/device".

ATTR{filename}

Match sysfs attribute values of the soundcard device. The relative path to sysfs tree must be defined by CONFIG{sysfs_device} key. Trailing whitespace in the attribute values is ignored, if the specified match value does not contain trailing whitespace itself. Depending on the type of operator, this key is also used to set the value of a sysfs attribute.

ENV{key}

Match against the value of an environment variable. Up to five ENV keys can be specified per rule. Depending on the type of operator, this key is also used to export a variable to the environment.

PROGRAM

Execute external program. The key is true, if the program returns without exit code zero. The whole event environment is available to the executed program. The program's output printed to stdout is available for the RESULT key. Several buildin commands are available:

__ctl_search

Search for a control. The CTL{name} key might contain match characters * and ?. An control index might be specified as first argument starting from zero (e.g. PROGRAM="__ctl_search 2").

__ctl_count

Search for a controls and return total count of matched ones. The CTL{name} key might contain match characters * and ?.

RESULT

Match the returned string of the last PROGRAM call. This key can be used in the same or in any later rule after a PROGRAM call.

Most of the fields support a shell style pattern matching. The following pattern characters are supported:

*

Matches zero, or any number of characters.

?

Matches any single character.

[]

Matches any single character specified within the brackets. For example, the pattern string 'tty[SR]' would match either 'ttyS' or 'ttyR'. Ranges are also supported within this match with the '-' character. For example, to match on the range of all digits, the pattern [0-9] would be used. If the first character following the '[' is a '!', any characters not enclosed are matched.

The following keys can get values assigned:

CTL{numid}, CTL{iface}, CTL{device}, CTL{subdev}, CTL{name}, CTL{index},

Select universal control element.

CTL{value}

Value is set (written) also to soundcard's control device and RESULT key is set to errno code. The result of set operation is always true (it means continue with next key on line).

CTL{values}

Value is set (written) also to soundcard's control device (all control values are set to specified value) and RESULT key is set to errno code. The result of set operation is always true (it means continue with next key on line).

CTL{write}

Value is set (written) also to soundcard's control device (all control values are set to specified value). The result of set operation is true when operation succeed (it means continue with next key on line).

ENV{key}

Export a variable to the environment. Depending on the type of operator, this key is also to match against an environment variable.

RESULT

Set RESULT variable. Note that PROGRAM also sets this variable, but setting this variable manually might be useful to change code execution order (included files).

LABEL

Named label where a GOTO can jump to.

GOTO

Jumps to the next LABEL with a matching name. The goto cannot jump backward.

INCLUDE

Include the specified filename or files in specified directory. When a directory is specified, only the files with the extension ".conf" are read. Also they are read in the alphabetical order. Thus it's highly recommended to use some number prefix (e.g. "01-something.conf") to assure the order of execucions.

ACCESS

Check if specified file or directory exists

CONFIG{sysfs_device}

The relative path to sysfs subsystem specifying the root directory of a soundcard device. Usually, it should be set to "/class/sound/card$cardinfo{card}/device".

PRINT

PRINT value to stdout.

ERROR

PRINT value to stderr.

EXIT

Exit immediately and set program exit code to value (should be integer). If value is "return" string, parser leaves current included file and returns to parent configuration file.

The PROGRAM, RESULT, CTL{value}, PRINT, ERROR, EXIT, CONFIG{} fields support simple printf-like string substitutions. It allows the use of the complete environment set by earlier matching rules. For all other fields, substitutions are applied while the individual rule is being processed. The available substitutions are:

$cardinfo{attribute}, %i{attribute}

See CARDINFO{} for more details.

$ctl{attribute}, %C{attribute}

See CTL{} for more details.

$attr{file}, %s{file}

The value of a sysfs attribute found at the device, where all keys of the rule have matched. If the attribute is a symlink, the last element of the symlink target is returned as the value.

$env{key}, %E{key}

The value of an environment variable.

$result, %c

The string returned by the external program requested with PROGRAM. A single part of the string, separated by a space character may be selected by specifying the part number as an attribute: %c{N}. If the number is followed by the '+' char this part plus all remaining parts of the result string are substituted: %c{N+}

$sysfsroot, %r

Root directory where sysfs file-system is mounted. Ususally, this value is just "/sys".

$config{key}, %g{key}

The value of a configuration variable. See CONFIG{} for more details.

%%

The '%' character itself.

$$

The '$' character itself.

The count of characters to be substituted may be limited by specifying the format length value. For example, '%3s{file}' will only insert the first three characters of the sysfs attribute

## AUTHOR
Written by Jaroslav Kysela <perex@perex.cz>

Some portions are written by Greg Kroah-Hartman <greg@kroah.com> and Kay Sievers <kay.sievers@vrfy.org>.

## SEE ALSO
alsactl(1)


amt-howto

package: amtterm

title: amt-howto(7)

text:
# amt-howto(7)

## NAME
amt-howto - Intel AMT with linux mini howto

## DESCRIPTION

### What is AMT and why I should care?
AMT stands for "Active Management Technology". It provides some remote management facilities. They are handled by the hardware and firmware, thus they work independant from the operation system. Means: It works before Linux bootet up to the point where it activated the network interface. It works even when your most recent test kernel deadlocked the machine. Which makes it quite useful for development machines ...

Intel AMT is part of the vPro Platform. Recent intel-chipset based business machines should have it. My fairly new Intel SDV machine has it too.

### Documentation
Look here for documentation beyond this mini howto:

http://www.intel.com/technology/platform-technology/intel-amt/

Most useful to get started: "Intel AMT Deployment and Reference Guide"

### Very short AMT enabling instructions.
Enter BIOS Setup.

* Enable AMT

Enter ME (Management Extention) Setup. Ctrl-P hotkey works for me.

* Login, factory default password is "admin".

* Change password. Trivial ones don't work, must include upper- and lowercase letters, digits, special characters.

* Enable AMT Managment.

Reboot, Enter ME Setup again with AMT enabled.

* Configure AMT (hostname, network config, ...)

* Use SMB (Small Business) management mode. The other one (Enterprise) requires Active Directory Service Infrastructure, you don't want that, at least not for your first steps ...

### Testing AMT
Take your browser, point it to http://machine:16992/. If you configured AMT to use DHCP (which is the default) the OS and the management stack share the same IP address.

You must do that from a remote host as the NIC intercepts network packets for AMT, thus it doesn't work from the local machine as the packets never pass the NIC then. If everything is fine you'll see a greeting page with a button for login.

You can login now, using "admin" as username and the password configured during setup. You'll see some pages with informations about the machine. You can also change AMT settings here.

### Control Machine
You might have noticed already while browing the pages: There is a "Remote Control" page. You can remotely reset and powercycle the machine there, thus recover the machine after booting a b0rken kernel, without having someone walk over to the machine and hit the reset button.

### Serial-over-LAN (SOL) console
AMT also provides a virtual serial port which can be accessed via network. That gives you a serial console without a serial cable to another machine.

If you have activated AMT and SOL the linux kernel should see an additional serial port, like this on my machine:

```
  [root@xeni ~]# dmesg | grep ttyS2

  0000:00:03.3: ttyS2 at I/O 0xe000 (irq = 169) is a 16550A
```

Edit initab, add a line like this:

```
  S2:2345:respawn:/sbin/agetty ttyS2 115200 vt100-nav
```

You should add the serial port to /etc/securetty too so you are able to login as root. Reload inittab ("init q"). Use amtterm to connect. Tap enter. You should see a login prompt now and be able to login.

You can also use that device as console for the linux kernel, using the usual "console=ttyS2,115200" kernel command line argument, so you see the boot messages (and kernel Oopses, if any).

You can tell grub to use that serial device, so you can pick a working kernel for the next boot. Usual commands from the grub manual, except that you need "--port=0xe000" instead of "--unit=0" due to the non-standard I/O port for the serial line (my machine, yours might use another port, check linux kernel boot messages).

The magic command for the Xen kernel is "com1=115200,8n1,0xe000,0" (again, you might have to replace the I/O port). The final '0' disables the IRQ, otherwise the Xen kernel hangs at boot after enabling interrupts.

### Fun with Xen and AMT
The AMT network stack seems to become slightly confused when running on a Xen host in DHCP mode. Everything works fine as long as only Dom0 runs. But if one starts a guest OS (with bridged networking) AMT suddenly changes the IP address to the one the guest aquired via DHCP.

It is probably a good idea to assign a separate static IP address to AMT then. I didn't manage to switch my machine from DHCP to static IP yet though, the BIOS refuses to accept the settings. The error message doesn't indicate why.

### More fun with AMT
You might want to download the DTK (Developer Toolkit, source code is available too) and play with it. The .exe is a self-extracting rar archive and can be unpacked on linux using the unrar utility. The Switchbox comes with a linux binary (additionally to the Windows stuff). The GUI tools are written in C#. Trying to make them fly with mono didn't work for me though (mono version 1.2.3 as shipped with Fedora 7).

## SEE ALSO
amtterm(1), gamt(1), amttool(1)

http://www.intel.com/technology/platform-technology/intel-amt/

## WRITTEN BY
Gerd Hoffmann <kraxel@redhat.com>


atf

package: atf-tests

title: atf(7)

text:
# atf(7)

## NAME
ATF — introduction to the Automated Testing Framework

## DESCRIPTION
The Automated Testing Framework (ATF) is a collection of libraries to implement test programs in a variety of languages. These libraries all offer similar functionality and any test program written with them exposes a consistent user interface.

Test programs using the ATF libraries rely on a separate runtime engine to execute them in a deterministic fashion. The runtime engine isolates the test programs from the rest of the system and ensures some common side-effects are cleaned up. The runtime engine is also responsible for gathering the results of all tests and composing reports. The current runtime of choice is Kyua, described in kyua(1).

If your operating systems distributes ATF, it should also provide an introductory tests(7) manual page. You are encouraged to read it now.

The rest of this manual page serves as a cross-reference to all the other documentation shipped with ATF.

### Language bindings
atf-c(3)

C programming interface.

atf-c++(3)

C++ programming interface.

atf-sh(3)

sh(1) programming interface.

### Miscellaneous pages
atf-test-case(4)

Generic description of test cases, independent of the language they are implemented in.

atf-test-program(1)

Common interface provided by the test programs written using the ATF libraries.

## SEE ALSO
kyua(1), tests(7)

## HISTORY
ATF started as a Google Summer of Code 2007 project mentored by The NetBSD Foundation. Its original goal was to provide a testing framework for the NetBSD operating system, but it grew as an independent project because the framework itself did not need to be tied to a specific operating system.

Originally, ATF shipped the collection of libraries described in this manual page as well as a runtime engine. The runtime engine has since been replaced by Kyua and the old tools were removed in 0.20, which shipped in early 2014.

As of late 2014, both FreeBSD and NetBSD ship ATF in their base systems and provide extensive test suites based on it.

For more details on historical changes, refer to:

```
/usr/share/doc/atf/NEWS
```

## AUTHORS
For more details on the people that made ATF possible, refer to:

```
/usr/share/doc/atf/AUTHORS
```


audit.rules

package: audit

title: audit.rules(7)

text:
# audit.rules(7)

## NAME
audit.rules - a set of rules loaded in the kernel audit system

## DESCRIPTION
audit.rules is a file containing audit rules that will be loaded by the audit daemon's init script whenever the daemon is started. The auditctl program is used by the initscripts to perform this operation. The syntax for the rules is essentially the same as when typing in an auditctl command at a shell prompt except you do not need to type the auditctl command name since that is implied. The audit rules come in 3 varieties: control, file, and syscall.

### Control
Control commands generally involve configuring the audit system rather than telling it what to watch for. These commands typically include deleting all rules, setting the size of the kernel's backlog queue, setting the failure mode, setting the event rate limit, or to tell auditctl to ignore syntax errors in the rules and continue loading. Generally, these rules are at the top of the rules file.

### File System
File System rules are sometimes called watches. These rules are used to audit access to particular files or directories that you may be interested in. If the path given in a watch rule is a directory, then the rule used is recursive to the bottom of the directory tree excluding any directories that may be mount points. The syntax of these watch rules generally follow this format:

```
-w path-to-file -p permissions -k keyname
```

where the permission are any one of the following:

r

- read of the file

w

- write to the file

x

- execute the file

a

- change in the file's attribute

Watches can also be created using the syscall format described below which allow for greater flexibility and options. Using syscall rules you can choose between path and dir which is against a specific inode or directory tree respectively. It should also be noted that the recursive directory watch will stop if there is a mount point below the parent directory. There is an option to make the mounted subdirectory equivalent by using a -q rule.

### System Call
The system call rules are loaded into a matching engine that intercepts each syscall that all programs on the system makes. Therefore it is very important to only use syscall rules when you have to since these affect performance. The more rules, the bigger the performance hit. You can help the performance, though, by combining syscalls into one rule whenever possible.

The Linux kernel has 6 rule matching lists or filters as they are sometimes called. They are: task, exit, user, exclude, filesystem, and io_uring. The task list is checked only during the fork or clone syscalls. It is rarely used in practice.

The exit filter is the place where all syscall and file system audit requests are evaluated.

The user filter is used to filter (remove) some events that originate in user space. By default, any event originating in user space is allowed. So, if there are some events that you do not want to see, then this is a place where some can be removed. See auditctl(8) for fields that are valid.

The exclude filter is used to exclude certain events from being emitted. The msgtype and a number of subject attribute fields can be used to tell the kernel which message types you do not want to record. This filter can remove the event as a whole and is not selective about any other attribute. The user and exit filters are better suited to selectively auditing events. The action is ignored for this filter, defaulting to "never".

The io_uring filter is used to watch underlying syscalls performed by io_uring operations.

Syscall rules take the general form of:

```
-a action,list -S syscall -F field=value -k keyname
```

The -a option tells the kernel's rule matching engine that we want to append a rule at the end of the rule list. But we need to specify which rule list it goes on and what action to take when it triggers. Valid actions are:

always

- always create an event

never

- never create an event

The action and list are separated by a comma but no space in between. Valid lists are: task, exit, user, exclude, filesystem, and io_uring. Their meaning was explained earlier.

Next in the rule would normally be the -S option. This field can either be the syscall name or number. For readability, the name is almost always used. You may give more than one syscall in a rule by specifying another -S option. When sent into the kernel, all syscall fields are put into a mask so that one compare can determine if the syscall is of interest. So, adding multiple syscalls in one rule is very efficient. When you specify a syscall name, auditctl will look up the name and get its syscall number. This leads to some problems on bi-arch machines. The 32 and 64 bit syscall numbers sometimes, but not always, line up. So, to solve this problem, you would generally need to break the rule into 2 with one specifying -F arch=b32 and the other specifying -F arch=b64. This needs to go in front of the -S option so that auditctl looks at the right lookup table when returning the number.

After the syscall is specified, you would normally have one or more -F options that fine tune what to match against. Rather than list all the valid field types here, the reader should look at the auditctl man page which has a full listing of each field and what it means. But it's worth mentioning a couple things.

The audit system considers uids to be unsigned numbers. The audit system uses the number -1 to indicate that a loginuid is not set. This means that when it's printed out, it looks like 4294967295. But when you write rules, you can use either "unset" which is easy to remember, or -1, or 4294967295. They are all equivalent. If you write a rule that you wanted try to get the valid users of the system, you need to look in /etc/login.defs to see where user accounts start. For example, if UID_MIN is 1000, then you would also need to take into account that the unsigned representation of -1 is higher than 500. So you would address this with the following piece of a rule:

```
-F auid>=1000 -F auid!=unset
```

These individual checks are "anded" and both have to be true.

The last thing to know about syscall rules is that you can add a key field which is a free form text string that you want inserted into the event to help identify its meaning. This is discussed in more detail in the NOTES section.

## NOTES
The purpose of auditing is to be able to do an investigation periodically or whenever an incident occurs. A few simple steps in planning up front will make this job easier. The best advice is to use keys in both the watches and system call rules to give the rule a meaning. If rules are related or together meet a specific requirement, then give them a common key name. You can use this during your investigation to select only results with a specific meaning.

When doing an investigation, you would normally start off with the main aureport output to just get an idea about what is happening on the system. This report mostly tells you about events that are hard coded by the audit system such as login/out, uses of authentication, system anomalies, how many users have been on the machine, and if SE Linux has detected any AVCs.

```
aureport --start this-week
```

After looking at the report, you probably want to get a second view about what rules you loaded that have been triggering. This is where keys become important. You would generally run the key summary report like this:

```
aureport --start this-week --key --summary
```

This will give an ordered listing of the keys associated with rules that have been triggering. If, for example, you had a syscall audit rule that triggered on the failure to open files with EPERM that had a key field of access like this:

```
-a always,exit -F arch=b64 -S open -S openat -S openat2 -F exit=-EPERM -k access
```

Then you can isolate these failures with ausearch and pipe the results to aureport for display. Suppose your investigation noticed a lot of the access denied events. If you wanted to see the files that unauthorized access has been attempted, you could run the following command:

```
ausearch --start this-week -k access --raw | aureport --file --summary
```

This will give an ordered list showing which files are being accessed with the EPERM failure. Suppose you wanted to see which users might be having failed access, you would run the following command:

```
ausearch --start this-week -k access --raw | aureport --user --summary
```

If your investigation showed a lot of failed accesses to a particular file, you could run the following report to see who is doing it:

ausearch --start this-week -k access -f /path-to/file --raw | aureport --user -i

This report will give you the individual access attempts by person. If you needed to see the actual audit event that is being reported, you would look at the date, time, and event columns. Assuming the event was 822 and it occurred at 2:30 on 09/01/2009 and you use the en_US.utf8 locale, the command would look something like this:

```
ausearch --start 09/01/2009 02:30 -a 822 -i --just-one
```

This will select the first event from that day and time with the matching event id and interpret the numeric values into human readable values.

The most important step in being able to do this kind of analysis is setting up key fields when the rules were originally written. It should also be pointed out that you can have more than one key field associated with any given rule.

## TROUBLESHOOTING
If you are not getting events on syscall rules that you think you should, try running a test program under strace so that you can see the syscalls. There is a chance that you might have identified the wrong syscall.

If you get a warning from auditctl saying, "32/64 bit syscall mismatch in line XX, you should specify an arch". This means that you specified a syscall rule on a bi-arch system where the syscall has a different syscall number for the 32 and 64 bit interfaces. This means that on one of those interfaces you are likely auditing the wrong syscall. To solve the problem, re-write the rule as two rules specifying the intended arch for each rule. For example,

```
-a always,exit -S openat -k access
```

would be rewritten as

```
-a always,exit -F arch=b32 -S openat -k access
-a always,exit -F arch=b64 -S openat -k access
```

If you get a warning that says, "entry rules deprecated, changing to exit rule". This means that you have a rule intended for the entry filter, but that filter is no longer available. Auditctl moved your rule to the exit filter so that it's not lost. But to solve this so that you do not get the warning any more, you need to change the offending rule from entry to exit.

## EXAMPLES
The following rule shows how to audit failed access to files due to permission problems. Note that it takes two rules for each arch ABI to audit this since file access can fail with two different failure codes indicating permission problems.

```
-a always,exit -F arch=b32 -S open -S openat -S openat2 -F exit=-EACCES -k access
-a always,exit -F arch=b32 -S open -S openat -S openat2 -F exit=-EPERM -k access
-a always,exit -F arch=b64 -S open -S openat -S openat2 -F exit=-EACCES -k access
-a always,exit -F arch=b64 -S open -S openat -S openat2 -F exit=-EPERM -k access
```

## IO_URING RULES
Io_uring rules do not take an arch field. It is implicit in the specification of the filter. The following example rule watches for file opens through the io_uring subsystem:

```
-a always,io_uring -S openat -S openat2 -F key=access
```

## HARD WIRED EVENTS
If auditing is enabled, then you can get any event that is not caused by syscall or file watch rules (because you don't have any rules loaded). So, that means, any event from 1100-1299, 1326, 1328, 1331 and higher can be emitted. The reason that there are a number of events that are hardwired is because they are required by regulatory compliance and are sent automatically as a convenience. (For example, logon/logoff is a mandatory event in all security guidance.) If you don't want this, you can use the exclude filter to drop events that you do not want.

```
-a always,exclude -F msgtype=CRED_REFR
```

## SEE ALSO
auditctl(8), auditd(8).

## AUTHOR
Steve Grubb


autopano-sift-c

package: autopano-sift-C

title: autopano-sift-c(7)

summary: Automatic panorama stitching package

text:
# autopano-sift-c(7)

## NAME
autopano-sift - Automatic panorama stitching package

## INTRODUCTION
The autopano-sift package contains a number programs to ease the creation of panoramic images. A tedious task in panoramic image creation from many individual images is the aligning of the images so they fit together. This is normally done by using control points which give information about shared image features. For example, image two images of a church. Lets assume both images overlap so that the rooftop of the church is visible in both. By telling a panorama software that the roof is in both images at a specific position the images can be aligned. At least three control point pairs between every two images are required usually.

The manual work of creating this control points can be immense. Especially for panorama images holding more than one line of images there is a huge number of possible overlaps.

The autopano-sift package can automatically create control point pairs by using a combination of sophisticated algorithms and models. For most feature-rich images it works very well, often outperforming humans in coverage, precision and speed.

In the following, the individual utilities are introduced. If you want a quick start, try the autopanog(1) GUI frontend.

## DESCRIPTION
autopanog The GTK# GUI frontend for generating and matching SIFT keypoints. As a user wanting to stitch panorama images, this is all you will ever need. See autopanog(1)

autopano The keypoint matching program. It can take SIFT keypoint files as input and produce PTO output files. See autopano(1)

generatekeys The SIFT keypoint extraction program. Takes an image from you, and gives keypoints back. Optionally can downscale the image to a given resolution, so your memory size is cared for. See generatekeys(1)

showone Show the SIFT keypoints overlayed over the source image. Use includes debugging and tuning of SIFT parameters and to get an impression how well spread the keypoints are. See showone(1)

showtwo Do simplistic matching of SIFT keypoints between two images, without geometric model. Use includes representing general matching quality. Optionally filter only a given number of "best" keypoint matches. See showtwo(1)

## BUGS
If you find any bugs in the programs, please mail the author.

## AUTHOR
Sebastian Nowozin <nowozin at cs dot tu dash berlin dot de>

## SEE ALSO
autopano(1), autopanog(1), generatekeys(1), showone(1), showtwo(1)


bats

package: bats

title: bats(7)

summary: Bats test file format

text:
# bats(7)

## NAME
bats - Bats test file format

## DESCRIPTION
A Bats test file is a Bash script with special syntax for defining test cases. Under the hood, each test case is just a function with a description.

```
#!/usr/bin/env bats
@test "addition using bc" {

  result="$(echo 2+2 | bc)"

  [ "$result" -eq 4 ]
}
@test "addition using dc" {

  result="$(echo 2 2+p | dc)"

  [ "$result" -eq 4 ]
}
```

Each Bats test file is evaluated n+1 times, where n is the number of test cases in the file. The first run counts the number of test cases, then iterates over the test cases and executes each one in its own process.

## Tagging tests
Each test has a list of tags attached to it. Without specification, this list is empty. Tags can be defined in two ways. The first being # bats test_tags=:

\# bats test_tags=tag:1, tag:2, tag:3 @test "second test" { # ... }

@test "second test" { # ... }

These tags (tag:1, tag:2, tag:3) will be attached to the test first test. The second test will have no tags attached. Values defined in the # bats test_tags= directive will be assigned to the next @test that is being encountered in the file and forgotten after that. Only the value of the last # bats test_tags= directive before a given test will be used.

Sometimes, we want to give all tests in a file a set of the same tags. This can be achieved via # bats file_tags=. They will be added to all tests in the file after that directive. An additional # bats file_tags= directive will override the previously defined values:

```
@test "Zeroth test" {

  # will have no tags
}
# bats file_tags=a:b
# bats test_tags=c:d
@test "First test" {

  # will be tagged a:b, c:d
}
# bats file_tags=
@test "Second test" {

  # will have no tags
}
```

Tags are case sensitive and must only consist of alphanumeric characters and _, -, or :. They must not contain whitespaces! The colon is intended as a separator for (recursive) namespacing.

Tag lists must be separated by commas and are allowed to contain whitespace. They must not contain empty tags like test_tags=,b (first tag is empty), test_tags=a,,c, test_tags=a, ,c (second tag is only whitespace/empty), test_tags=a,b, (third tag is empty).

Every tag starting with bats: (case insensitive!) is reserved for Bats´ internal use:

bats:focus

If any test with the tag bats:focus is encountered in a test suite, only those tagged with this tag will be executed. To prevent the CI from silently running on a subset of tests due to an accidentally commited bats:focus tag, the exit code of successful runs will be overriden to 1.

Should you require the true exit code, e.g. for a git bisect operation, you can disable this behavior by setting BATS_NO_FAIL_FOCUS_RUN=1 when running bats, but make sure to not commit this to CI!

## THE RUN HELPER
Usage: run [OPTIONS] [--]

Many Bats tests need to run a command and then make assertions about its exit status and output. Bats includes a run helper that invokes its arguments as a command, saves the exit status and output into special global variables, and (optionally) checks exit status against a given expected value. If successful, run returns with a 0 status code so you can continue to make assertions in your test case.

For example, let´s say you´re testing that the foo command, when passed a nonexistent filename, exits with a 1 status code and prints an error message.

```
@test "invoking foo with a nonexistent file prints an error" {

  run -1 foo nonexistent_filename

  [ "$output" = "foo: no such file ´nonexistent_filename´" ]
}
```

The -1 as first argument tells run to expect 1 as an exit status, and to fail if the command exits with any other value. On failure, both actual and expected values will be displayed, along with the invoked command and its output:

```
(in test file test.bats, line 2)

 `run -1 foo nonexistent_filename´ failed, expected exit code 1, got 127
```

This error indicates a possible problem with the installation or configuration of foo; note that a simple [ $status != 0 ] test would not have caught this kind of failure.

The $status variable contains the status code of the command, and the $output variable contains the combined contents of the command´s standard output and standard error streams.

A third special variable, the $lines array, is available for easily accessing individual lines of output. For example, if you want to test that invoking foo without any arguments prints usage information on the first line:

```
@test "invoking foo without arguments prints usage" {

  run -1 foo

  [ "${lines[0]}" = "usage: foo <filename>" ]
}
```

By default run leaves out empty lines in ${lines[@]}. Use run --keep-empty-lines to retain them.

Additionally, you can use --separate-stderr to split stdout and stderr into $output/$stderr and ${lines[@]}/${stderr_lines[@]}.

All additional parameters to run should come before the command. If you want to run a command that starts with -, prefix it with -- to prevent run from parsing it as an option.

## THE LOAD COMMAND
You may want to share common code across multiple test files. Bats includes a convenient load command for sourcing a Bash source file relative to the location of the current test file. For example, if you have a Bats test in test/foo.bats, the command

```
load test_helper
```

will source the script test/test_helper.bash in your test file. This can be useful for sharing functions to set up your environment or load fixtures.

## THE BATS_LOAD_LIBRARY COMMAND
Some libraries are installed on the system, e.g. by npm or brew. These should not be loaded, as their path depends on the installation method. Instead, one should use bats_load_library together with setting BATS_LIB_PATH, a PATH-like colon-delimited variable.

bats_load_library has two modes of resolving requests:

1.

by relative path from the BATS_LIB_PATH to a file in the library

2.

by library name, expecting libraries to have a load.bash entrypoint

For example if your BATS_LIB_PATH is set to ~/.bats/libs:/usr/lib/bats, then bats_load_library test_helper would look for existing files with the following paths:

○

~/.bats/libs/test_helper

○

~/.bats/libs/test_helper/load.bash

○

/usr/lib/bats/test_helper

○

/usr/lib/bats/test_helper/load.bash

The first existing file in this list will be sourced.

If you want to load only part of a library or the entry point is not named load.bash, you have to include it in the argument: bats_load_library library_name/file_to_load will try

○

~/.bats/libs/library_name/file_to_load

○

~/.bats/libs/library_name/file_to_load/load.bash

○

/usr/lib/bats/library_name/file_to_load

○

/usr/lib/bats/library_name/file_to_load/load.bash

Apart from the changed lookup rules, bats_load_library behaves like load.

Note: As seen above load.bash is the entry point for libraries and meant to load more files from its directory or other libraries.

Note: Obviously, the actual BATS_LIB_PATH is highly dependent on the environment. To maintain a uniform location across systems, (distribution) package maintainers are encouraged to use /usr/lib/bats/ as the install path for libraries where possible. However, if the package manager has another preferred location, like npm or brew, you should use this instead.

## THE SKIP COMMAND
Tests can be skipped by using the skip command at the point in a test you wish to skip.

```
@test "A test I don´t want to execute for now" {

  skip

  run -0 foo
}
```

Optionally, you may include a reason for skipping:

```
@test "A test I don´t want to execute for now" {

  skip "This command will return zero soon, but not now"

  run -0 foo
}
```

Or you can skip conditionally:

```
@test "A test which should run" {

  if [ foo != bar ]; then

    skip "foo isn´t bar"

  fi

  run -0 foo
}
```

## THE BATS_REQUIRE_MINIMUM_VERSION COMMAND
Code for newer versions of Bats can be incompatible with older versions. In the best case this will lead to an error message and a failed test suite. In the worst case, the tests will pass erroneously, potentially masking a failure.

Use bats_require_minimum_version <Bats version number> to avoid this. It communicates in a concise manner, that you intend the following code to be run under the given Bats version or higher.

Additionally, this function will communicate the current Bats version floor to subsequent code, allowing e.g. Bats´ internal warning to give more informed warnings.

Note: By default, calling bats_require_minimum_version with versions before Bats 1.7.0 will fail regardless of the required version as the function is not available. However, you can use the bats-backports plugin (https://github.com/bats-core/bats-backports) to make your code usable with older versions, e.g. during migration while your CI system is not yet upgraded.

## SETUP AND TEARDOWN FUNCTIONS
You can define special setup and teardown functions which run before and after each test case, respectively. Use these to load fixtures, set up your environment, and clean up when you´re done.

## CODE OUTSIDE OF TEST CASES
You can include code in your test file outside of @test functions. For example, this may be useful if you want to check for dependencies and fail immediately if they´re not present. However, any output that you print in code outside of @test, setup or teardown functions must be redirected to stderr (>&2). Otherwise, the output may cause Bats to fail by polluting the TAP stream on stdout.

## SPECIAL VARIABLES
There are several global variables you can use to introspect on Bats tests:

○

$BATS_TEST_FILENAME is the fully expanded path to the Bats test file.

○

$BATS_TEST_DIRNAME is the directory in which the Bats test file is located.

○

$BATS_TEST_NAMES is an array of function names for each test case.

○

$BATS_TEST_NAME is the name of the function containing the current test case.

○

BATS_TEST_NAME_PREFIX will be prepended to the description of each test on stdout and in reports.

○

$BATS_TEST_DESCRIPTION is the description of the current test case.

○

BATS_TEST_RETRIES is the maximum number of additional attempts that will be made on a failed test before it is finally considered failed. The default of 0 means the test must pass on the first attempt.

○

BATS_TEST_TIMEOUT is the number of seconds after which a test (including setup) will be aborted and marked as failed. Updates to this value in setup() or @test cannot change the running timeout countdown, so the latest useful update location is setup_file().

○

$BATS_TEST_NUMBER is the (1-based) index of the current test case in the test file.

○

$BATS_SUITE_TEST_NUMBER is the (1-based) index of the current test case in the test suite (over all files).

○

$BATS_TMPDIR is the base temporary directory used by bats to create its temporary files / directories. (default: $TMPDIR. If $TMPDIR is not set, /tmp is used.)

○

$BATS_RUN_TMPDIR is the location to the temporary directory used by bats to store all its internal temporary files during the tests. (default: $BATS_TMPDIR/bats-run-$BATS_ROOT_PID-XXXXXX)

○

$BATS_FILE_EXTENSION (default: bats) specifies the extension of test files that should be found when running a suite (via bats [-r] suite_folder/)

○

$BATS_SUITE_TMPDIR is a temporary directory common to all tests of a suite. Could be used to create files required by multiple tests.

○

$BATS_FILE_TMPDIR is a temporary directory common to all tests of a test file. Could be used to create files required by multiple tests in the same test file.

○

$BATS_TEST_TMPDIR is a temporary directory unique for each test. Could be used to create files required only for specific tests.

○

$BATS_VERSION is the version of Bats running the test.

## SEE ALSO
bash(1), bats(1)


biblesync

package: biblesync-devel

title: biblesync(7)

text:
# biblesync(7)

## NAME
biblesync - multicast navigation synchronization in Bible programs

## SYNOPSIS

```
#include <biblesync.hh>

typedef enum_BibleSync_mode {

    BSP_MODE_DISABLE,

    BSP_MODE_PERSONAL,

    BSP_MODE_SPEAKER,

    BSP_MODE_AUDIENCE,

    N_BSP_MODE

} BibleSync_mode;

typedef enum_BibleSync_xmit_status {

    BSP_XMIT_OK,

    BSP_XMIT_FAILED,

    BSP_XMIT_NO_SOCKET,

    BSP_XMIT_BAD_TYPE,

    BSP_XMIT_NO_AUDIENCE_XMIT,

    BSP_XMIT_RECEIVING,

    N_BSP_XMIT

} BibleSync_xmit_status;

#define BSP_ANNOUNCE   1

#define BSP_SYNC       2

#define BSP_BEACON     3

typedef void (*BibleSync_navigate)(char cmd, string speakerkey,

                                   string bible, string ref, string alt,

                                   string group, string domain,

                                   string info,  string dump);

Public interface:

BibleSync *object = new BibleSync(string application,

                                  string version,

                                  string user);

BibleSync_mode BibleSync::setMode(BibleSync_mode mode,

                                  BibleSync_navigate *nav_func,

                                  string passPhrase);

BibleSync_mode BibleSync::getMode(void);

string BibleSync::getVersion(void);

string BibleSync::getPassphrase(void);

BibleSync_xmit_status BibleSync::Transmit(string bible, string ref, string alt,

                                          string group, string domain);

static int BibleSync::Receive(void *object);

bool BibleSync::setPrivate(bool privacy);

void BibleSync::setBeaconCount(uint8_t count);

void BibleSync::listenToSpeaker(bool listen, string speakerkey);
```

## DESCRIPTION
BibleSync is a published protocol specification by which cooperating Bible programs navigate together. It is implemented as a C++ class providing a small, clean interface including basic setup, take-down, transmit, polled receive, and a bare few utility methods.

The value of BibleSync is found in several examples:

A single user may have multiple programs, or multiple computers/devices, all of which he wishes to follow along together.

Similarly, a group of people working closely together, such as translators, can stay together as they work.

In an instructional motif, BibleSync takes either the active or passive mode, providing for a unidirectional navigation control.

## BIBLESYNC ESSENTIALS
BibleSync communicates using local multicast. Three operational modes are provided: Personal, Speaker, or Audience.

In Personal mode, BibleSync operates as a peer among peers, both sending and receiving navigation synchronization on the shared local multicast network. Applications are expected to respond appropriately to navigation, and to send synchronization events of their own as the user moves about his Bible.

In Speaker or Audience mode, BibleSync either transmits only (Speaker) or receives only (Audience) navigation. The Audience is expected to follow along with the Speaker's direction. The Speaker ignores incoming navigation; the Audience transmits no navigation.

The difference between Personal and Speaker/Audience is thus strictly as to whether both sides of the conversation are active for each participant.

On startup of the protocol, BibleSync transmits a presence announcement, informing other communication partners of the application's participation. BibleSync makes this announcement available to the application; whether the application shows these announcements to the user is the application designer's choice.

Thereafter, as appropriate to the operational mode selected, BibleSync is tasked with polled reception of incoming navigation event packets and transmission of navigation event packets on the user's part.

Transmitters (Personal and Speaker modes) issue availability beacons every 10 seconds. Received beacons for previously-unknown Speakers are handed up to the application. These beacons provide for receivers (Personal and Audience modes) to maintain a managed list of available Speakers. Furthermore, when a transmitter ceases to issue beacons, its presence in the list of available Speakers is aged out until being removed after 30 seconds of beacon silence. The application is again informed when a Speaker goes dead.

Default listening behavior is that the first Speaker heard via beacon is marked for listening. Other transmitters claiming Speaker status via beacon are initially ignored, but their presence is made known to the application. This provides for the application to maintain a list from which the user can select Speakers he wishes to synchronize his application. It is useful for the application to provide blanket "listen to all" and "listen to none" functions, as well as per-Speaker selections, informing BibleSync of these choices. In any case, this default "first Speaker only" policy can be overridden by the application with any other policy desired, through the use of listenToSpeaker() as the application designer requires.

Synchronization events include 5 data elements: The Bible abbreviation; the verse reference; an alternate reference (if desired; not required) which may allow the application to interpret better based on variant versification; a synchronization group identifier; and the domain.

The group identifier is a single digit between 1 and 9. The specification is imprecise as to this parameter's use. The initial implementation of BibleSync in Xiphos uses the synchronization group as an indicator of the tab number in its tabbed interface: Not only is the Bible navigated, but the tab in which to navigate is selected.

The domain parameter is currently fixed as "BIBLE-VERSE". This will be put to greater use in future revisions of the protocol.

BibleSync transmits no packet when the application leaves the conversation.

Only the 3 packet types BSP_ANNOUNCE, BSP_SYNC, and BSP_BEACON are defined in the protocol.

## PUBLIC INTERFACE

### Object creation
The application must create a single BibleSync object, identifying the application's name, its version, and the user.

### setMode
setMode identifies how BibleSync should behave. The application must provide as well the navigation callback function by which BibleSync will inform the application of incoming events; the callback makes all the navigation parameters provided in event packets available to the application. setMode returns the resulting mode. The application provides the passphrase to be used as well; this argument defaults to "" (empty string), indicating that the existing passphrase should be left in place.

### getMode
The application may request the current mode.

### getVersion
The version string of the library itself is returned.

### getPassphrase
Intended for use when preparing to enter any active mode, the application may request the current passphrase, so as to provide a default.

### Transmit
The protocol requires all the indicated parameters, but all have defaults in Transmit: KJV, Gen.1.1, empty alternate, 1, and BIBLE-VERSE.

### Receive
This is a static method accessible from either C or C++. It must be called with the object pointer so as to re-enter object context for the private internal receiver. Receive() must be called regularly (i.e. polled) as long as it continues to return TRUE. When it returns FALSE, it means that the mode has changed to BSP_MODE_DISABLE, and the scheduled polling should stop. See also the note below on polled reception.

### setPrivate
In the circumstance where the user has multiple programs running on a single computer and does not want his navigation broadcast outside that single system, when in Personal mode, the application may also request privacy. The effect is to set multicast TTL to zero, meaning that packets will not go out on the wire.

### setBeaconCount
Beacon transmission occurs during every Nth call to Receive(); the default value is 10. This presumes the application will call Receive() once per second. If the application will call Receive() less frequently, divide that time (say, 2 seconds) into 10 to get a value (5) to use with this call. Use setBeaconCount() prior to enabling Personal or Speaker mode.

### listenToSpeaker
Aside from default listen behavior detailed above, the application specifically asks to listen or not to listen to specific Speakers. The key is as provided during the notification of a new Speaker.

## RECEIVE USE CASES
There are 6 values for the cmd parameter of the nav_func. In all cases, the dump parameter provides the raw content of an arriving packet.

### 'A'
Announce. A general presence message is in alt, and the individual elements are also available, as overloaded use of the parameters: bible contains the user; ref contains the IP address; group contains the application name and version; and domain contains the device identification.

### 'N'
Navigation. The bible, ref, alt, group, and domain parameters are presented as they arrived. info and dump are also available.

### 'S'
Speaker's initial recognition from beacon receipt. Overloaded parameters are available as for presence announcements.

### 'D'
Dead Speaker. speakerkey holds the UUID key of a previously-identified application which is no longer a candidate for listening.

### 'M'
Mismatch. The incoming event packet is mismatched, either against the current passphrase or for a navigation synchronization packet when BibleSync is in Speaker mode. The info parameter begins with either "announce" or "sync", plus the user and IP address from whom the packet came. As well, in the sync case, the regular bible, ref, alt, group, and domain parameters are available. In the announce case, the presence message is in alt, with overloaded individual parameters as previously described.

### 'E'
Error. This indicates network errors and malformed packets. The application's nav_func is provided only the info and dump parameters.

## NOTES

### Polled reception
The application must provide a means by which to poll regularly for incoming packets. In Xiphos, which is built on GTK and GLib, this is readily provided by mechanisms like g_timeout_add(), which sets a regular interval call of the indicated function. GLib will re-schedule the call as long as the called function returns TRUE. When it returns FALSE, GLib un-schedules the call. Receive() adheres to this straightforward convention. Therefore, it is imperative that every time the application moves from disabled to any non-disabled mode, Receive is again scheduled for polled use.

A 1-second poll interval is expected. Brief experience during development has shown that longer intervals lead to a perception of lag.

During every Receive() call, all waiting packets are processed.

### No datalink security
BibleSync is a protocol defined for a friendly environment. It offers no security in its current specification, and any packet sniffer such as wireshark(1) or tcpdump(8) can see the entire conversation. The specification makes passing reference to future encryption, but at this time none is implemented.

### Managed Speaker lists
The addition of transmitter beacons was a result of initial experience showing that it can be too easy for a user to mis-start BibleSync, or for a malicious user to interject himself into serious work. The goal of beacons is to provide a means by which, on the one hand, the user can be made aware of who is attempting to be a Speaker and, on the other hand, confine the set of Speakers whom the user will permit to make synchronization changes in the application. The simplest use of 'S' new Speaker notification events is to respond with listenToSpeaker(true, speakerkey) which in effect makes BibleSync behave as though there are no beacons. More serious use of 'S'/'D' is for the application to manage its own sense of available Speakers, providing a means by which the user can make sensible selections about how to react to each Speaker's presence. BibleSync can be told to listen to legitimate Speakers, and to ignore interlopers, whether intended maliciously or merely due to other users' inadvertent behavior.

### Sending verse lists
One of the better uses of BibleSync is in sharing verse lists. Consider a relatively weak application, perhaps on a mobile device, and a desktop-based application with strong search capability. Run searches on the desktop, and send the result via BibleSync to the mobile app. The ref parameter is not confined to a single reference. In normal citation syntax, the verse reference may consist of semicolon-separated references, comma-separated verses, and hyphen-separated ranges. Be aware that the specification has a relatively short limit on packet size, so that at most a few dozen references will be sent.

### Standard reference syntax
It is the responsibility of the application to transmit references in standard format. BibleSync neither validates nor converts the application's incoming bible, ref, and alt parameters. The specification references the BibleRef and OSIS specifications.

## SEE ALSO
http://biblesyncprotocol.wikispaces.com (user "General_Public", password "password"), http://semanticbible.com/bibleref/bibleref-specification.html, socket(2), setsockopt(2), select(2), recvfrom(2), sendto(2), and ip(7), especially sections on IP_ADD_MEMBERSHIP, IP_MULTICAST_IF, IP_MULTICAST_LOOP, and IP_MULTICAST_TTL.


blogc-pagination

package: blogc

title: blogc-pagination(7)

summary: blogc\'s pagination support

text:
# blogc-pagination(7)

## NAME
blogc-pagination - blogc´s pagination support

## DESCRIPTION
blogc(1) supports some basic pagination and post filtering, when running on listing mode. Files are listed in the order that they are provided to blogc(1) in the command line, no sorting is done.

## PAGINATION PARAMETERS
blogc(1) accepts some variables as -D options, that are used to filter the files passed as arguments to it:

FILTER_PAGE

Integer, current page. If calling blogc(1) with 10 files, FILTER_PER_PAGE=4 and FILTER_PAGE=3, it will return just the 2 last files, skipping the first 2 pages with 4 files each one.

FILTER_PER_PAGE

Integer, limits the maximum number of files to be listed. If negative or 0, no posts are included. Have no effect if FILTER_PAGE is not defined.

FILTER_TAG

String, if defined, blogc(1) will only list files that declare a TAGS variable, as a space-separated list of tags (tags can´t have spaces, obviously). See blogc-source(7) for details about how to define source variables. The pagination filters will only act on the files with the provided tag, instead of filtering the whole file set.

FILTER_REVERSE

Boolean (1/y/yes/true/on), if set, blogc(1) will list files in reverse order. This filter is combined with FILTER_SORT, and all the other filters will get the files already in the reverse order.

FILTER_SORT

Boolean (1/y/yes/true/on), if set, blogc(1) will sort files using the DATE variable provided in the files, instead of respecting the order of the source files provided to blogc(1). The files are sorted in descending order and combined with FILTER_REVERSE, that will result in the files sorted in ascending order. All the other filters will get the files already sorted.

## TEMPLATE VARIABLES
blogc(1) will export some global blogc-template(7) variables, that can be used to build links for next and previous page.

CURRENT_PAGE

Integer, usually the same value of FILTER_PAGE pagination paramenter, if defined, or 1.

FIRST_PAGE

Integer, 1 if more than zero files were listed.

LAST_PAGE

Integer, last page available if more than zero files were listed.

PREVIOUS_PAGE

Integer, CURRENT_PAGE minus 1, if CURRENT_PAGE is bigger than 1.

NEXT_PAGE

Integer, CURRENT_PAGE plus 1, if LAST_PAGE is bigger than CURRENT_PAGE.

blogc(1) can output the value of the variables after evaluation, instead of actually rendering the files, using the -p option. See blogc(1) for details. This is useful to know the last page that needs to be built, using -p LAST_PAGE, for example.

### Date variables
blogc(1) will also export some global blogc-template(7) variables related to the DATE variable, as specified in blogc-source(7).

DATE_FIRST

String, DATE variable from the first file in the listing.

DATE_LAST

String, DATE variable from the last file in the listing.

These variables can be also formatted with DATE_FORMAT global blogc(1) parameter, if provided, using DATE_FIRST_FORMATTED and DATE_LAST_FORMATTED global template variables.

### File name variables
blogc(1) will also export some global blogc-template(7) variables related to the FILENAME variable, as automatically exported by the source file parser, see blogc-source(7) for details.

FILENAME_FIRST

String, FILENAME variable from the first file in the listing.

FILENAME_LAST

String, FILENAME variable from the last file in the listing.

## EXAMPLES

### Source file with tags

```
TITLE: My post
TAGS: foo bar baz
-----------------
Post content
```

This source file defines 3 tags: foo, bar and baz.

### Template with pagination

```
{% block listing_once %}
<ul class="pager">

    {% ifdef PREVIOUS_PAGE %}

    <li class="previous">

        <a href="/page/{{ PREVIOUS_PAGE }}/">← Newer</a>

    </li>

    {% endif %}

    {% ifdef NEXT_PAGE %}

    <li class="next">

        <a href="/page/{{ NEXT_PAGE }}/">Older →</a>

    </li>

    {% endif %}
</ul>
{% endblock %}
```

This example does not uses all the variables, but the concept is the same for all of them.

## BUGS
Please report any issues to: https://github.com/blogc/blogc

## AUTHOR
Rafael G. Martins <rafael@rafaelmartins.eng.br>

## SEE ALSO
blogc(1), blogc-source(7), blogc-template(7)


blogc-source

title: blogc-source(7)

summary: blogc\'s source file format

text:
# blogc-source(7)

## NAME
blogc-source - blogc´s source file format

## DESCRIPTION
Source files are used as input data to the blogc(1) compiler. They provide variables and content, that are used by the compiler to fill the gaps available in the templates (see blogc-template(7)).

The syntax of the source files is designed to be as simple as possible. The variables are defined in the top of the file as key-value lines, and the content is defined right after the variables.

Content is written in a markup language that is similar to John Gruber´s Markdown, but that is NOT Markdown. This language is very simple, while powerful enough to write big posts.

Content must be valid UTF-8.

## SOURCE VARIABLES
Variables are key-value lines. The variable name must be upper-case, starting with a letter and following with one or more letters and/or underscores. The value is separated from the variable name with a ´:´ and finishes in the end of the line. Multi-line values are not supported.

```
VARIABLE1: Value of variable one
VARIABLE2: Value of variable two
--------------------------------
```

All the variables defined in the source files are local and will override global variables provided to blogc(1) in the command-line, but just inside blocks that handle local variables. See blogc-template(7) for details.

The DATE variable is special, and represents the publishing date of the post. It may be formatted with the DATE_FORMAT variable, if provided, otherwise will be kept as is. The proper way to access the date from the template is to use the DATE_FORMATTED variable, that will contain the formatted date, or the original date, depending on whether the DATE_FORMAT variable is provided or not.

The DATE variable should be in the following format: yyyy-mm-dd hh:mm:ss. You can omit seconds, minutes and hours if you want, they will be filled with ´0´. Allowed formats are yyyy-mm-dd hh:mm:ss, yyyy-mm-dd hh:mm, yyyy-mm-dd hh and yyyy-mm-dd

The DATE_FORMAT variable should be passed to blogc(1) as a global variable. Its value must be a valid strftime(3) format.

The source parser will also automatically generate a variable called FILENAME, that stores the name of the source file, without its extension. This is useful for building permalinks in templates. This variable can´t be overriden by an explicit definition in source file.

The variable FIRST_HEADER is created by the source parser by default, containing the unparsed value of the first header found in the source file. The content is not parsed but HTML entities are encoded. Headers inside blockquotes are ignored. This variable can be overriden by an explicit definition in source file, that must have the HTML entities escaped manually.

Another variable, DESCRIPTION, will be automatically created by the source parser. It contains the unparsed content of the first paragraph found in the source file. The content is not parsed but HTML entities are encoded. Paragraphs inside blockquotes are ignored. This variable can be overriden by an explicit definition in source file, that must have the HTML entities escaped manually. This is useful to add "description" meta-tags to HTML templates. It may be needed to truncate the variable size to an maximum length, take a look at blogc-template(7).

## SOURCE CONTENT - BLOCK ELEMENTS

### Paragraphs
Paragraphs are simple blocks of text.

```
This is a paragraph.
This is another paragraph.
```

### Headers
Headers are defined starting with ´#´ characters, then number of characters is the level of the header.

```
# H1
## H2
### H3
#### H4
```

Each header will have an id attribute, that is a lowercase version of the unparsed header title, with non-alphanumeric characters replaced by ´-´. These ids can be used to create anchor links to specific sections of your content.

### Blockquotes
Blockquotes are defined with lines starting with ´>´ characters. Content defined inside a blockquote is parsed again, so all the block elements are allowed inside blockquotes. The indentation after the ´>´ character must be preserved in the begin of each blockquote line.

```
> Hello,
>
> This is the blockquote example!
```

### Unordered Lists
Unordered lists are defined with lines starting with ´*´, ´+´ or ´-´. The same starting character must be used for all the list items, and the indentation after the starting character must be preserved in the begin of each line.

```
* First item
* Second item
* Third item
```

Multi-line items are supported. Content must be aligned properly:

```
* First item

  Continuation of first item
* Second item
* Third item
```

### Ordered Lists
Ordered lists are defined with lines starting with a number and a ´.´ character. The indentation after the starting character must be preserved in the begin of each line, meaning that the content of the items must be aligned. The order and value of the numbers is ignored.

```
1.  First item
2.  Second item
10. Tenth item
```

Multi-line items are supported. Content must be aligned properly:

```
1.  First item

    Continuation of first item
2.  Second item
10. Tenth item
```

To use numbers with ´.´ character in a non-list string, you must escape the ´.´.

```
1234\. This is not a list
```

### Code Blocks
Code blocs are defined by indenting the lines with one or more whitespace characters.

```
This is a paragraph.

    This is a code block.

    Some more code.
This is another paragraph.
```

### Horizontal Rules
Horizontal rules are defined as a paragraph with a sequence of 2 or more ´*´, ´+´ or ´-´ characters.

```
This is a paragraph before horizontal rule
***
This is a paragraph after horizontal rule
```

The horizontal rule must not be on its own paragraph, otherwise it will be parsed as a continuation of the previous paragraph.

### HTML Blocks
HTML blocks are paragraphs started with ´<´ character. Everything is kept untouched in HTML blocks, until the next paragraph.

```
<p>This is raw HTML</p>
This is an usual paragraph
<p>This is more raw HTML</p>
```

### Excerpt Separator
The excerpt is separated from the full content of a page/post using a paragraph with a sequence of 2 or more ´.´ characters.

After parsing, the excerpt will be part of the full content as well.

## SOURCE CONTENT - INLINE ELEMENTS

### Bold
Bold text is defined with 2 ´*´ or ´_´ before and after the text.

```
Bold text: **text**
Bold text: __text__
```

### Italic
Italic text is defined with 1 ´*´ or ´_´ before and after the text.

```
Italic text: *text*
Italic text: _text_
```

### Bold and Italic
Bold and italic text is defined mixing markers, like:

```
Italic and bold text: _**text**_
Italic and bold text: *__text__*
Italic and bold text: __*text*__
Italic and bold text: **_text_**
```

### Code
Code is defined with 1 or 2 ´`´ before and after the text.

```
This is inline code: `code`
This is inline code: ``code``
```

The later form is particularly useful when a ´`´ is part of the code, because escaping delimiters with ´\´ is not possible.

### Images
Images are defined using the following syntax:

```
This is an image: This is the image alt text
```

Whitespace characters and new lines are allowed between alt text and image URL:

```
This is an image: ![This is the image alt text]
(picture.jpg)
```

### Links
Links are defined using the following syntax:

```
To learn more about blogc, [click here](https://blogc.rgm.io).
```

Whitespace characters and new lines are allowed between link text and link URL:

```
To learn more about blogc, [click here]
(https://blogc.rgm.io).
```

### Image Links
Links can be combined with images:

```
[This is the image alt text](https://blogc.rgm.io)
```

Whitespace characters and new lines are allowed between link text and link URL, and between alt text and image URL:

```
[![This is the image alt text]
(picture.jpg)]
(https://blogc.rgm.io)
```

### Automatic Links
Automatic link is defined with 2 ´[´ before and 2 ´]´ after the URL.

```
To learn more about blogc, visit [[https://blogc.rgm.io]].
```

### Line break
Line breaks can be added after a paragraph line adding 2 or more white spaces to the end of the line.

### En dashes and Em dashes
Sequences of 2 ´-´ characters are converted to an En dash HTML entity. Sequences of 3 ´-´ characters are converted to an Em dash HTML entity.

## BUGS
The source content is handled by handwritten parsers, that even being well tested, may be subject of parsing bugs. Please report any issues to: https://github.com/blogc/blogc

## AUTHOR
Rafael G. Martins <rafael@rafaelmartins.eng.br>

## SEE ALSO
blogc(1), blogc-template(7), strftime(3)