/ 
App-PFT-v1.0.6
River stage zero No dependents
/ pft

NAME

pft entry - Edit an entry

SYNOPSYS

pft entry -P [options] title of your page
pft entry -B [options] title of your blog page
pft entry -M [options] title of your month page
pft entry -T [options] title of your tag page

DESCRIPTION

The pft edit command allows to conveniently edit a text entry in a PFT site. It takes care of creating a skeleton for the new entries, to position them correctly within your PFT site, and to maintain their position consistent with the type of content.

All entries are stored under the ROOT/content directory, where ROOT is the base path of your PFT site. Each entry has the same format: a unicode text file composed by a YAML header concatenated with Markdown text content (more details later in this document).

There can be different kind of entries:

Regular Pages

Regular pages do not declare a date in their header. They get positioned in ROOT/content/pages. Their file name depends on their title.

Example:

C<ROOT/content/pages/hello-world>
Blog pages

Blog pages declare a full date (year, month and day) in their header. They get positioned in the ROOT/content/blog/YYYY-MM directory (where YYYY and MM correspond to the declared year and month respectively). Their file name starts with a DD- prefix, where DD corresponds to the declared day. The remaining part of the file name depends on their title.

Example:

C<ROOT/content/blog/2015-09/12-hello-world>
Month pages

Month pages are meant as entries summarizing a whole month. They are like blog pages, but the date defined in their headers lack of the day part (it is replaced by *). They are stored as ROOT/content/blog/YYYY-MM.month (where YYYY and MM represent the declared year and month).

Example:

C<ROOT/content/blog/2016-09.month>
Tag pages

All pages can optionally declare one or more tags. A tag can optionally be associated to a tag page.

For example, if your site has have a number of entries about cuisine, some of them might be tagged with the chicken tag. You may want to have a tag page entitled chicken, where you give a description of what chicken is (just in case someone doesn't know).

Tag pages are stored in ROOT/content/tags, and their file name depends on the tag title.

Example:

C<ROOT/content/tags/chicken>

OPTIONS

-P

Edit a page

A title is mandatory.

-B

Edit a blog page

If no title is specified, it defaults to today.

-M

Edit a month page

The title is optional.

-T

Edit a tag page

A title is mandatory.

--year=<y> | -y <y>

Defines a year for the edited entry. Implies -B unless -M is set.

This flag cannot be used if -P or -T are specified. It gets honored only when generating a header for the entry, that is if the file does not exist yet.

--month=<m> | -m <m>

Defines a month for the edited entry. Implies -B unless -M is set.

This flag cannot be used if -P or -T are specified. It gets honored only when generating a header for the entry, that is if the file does not exist yet.

--day=<d> | -d <d>

Defines a day for the edited entry. Implies -B unless -M is set.

This flag cannot be used if -P or -T are specified. It gets honored only when generating a header for the entry, that is if the file does not exist yet.

--author=<name> | -a <name>

Defines the author for the entry.

This flag gets honored only when generating a header for the entry, that is if the file does not exist yet.

--tag=<tag> | -t <tag>

This flag gets honored only when generating a header for the entry, that is if the file does not exist yet.

--resume | -r

Resume editing the most recent blog entry. Equivalent to --back 0, implies -B.

--back=<count> | -b <count>

Resume editing an old entry. The supplied parameter defines how many steps we should go back in history (0 means the most recent entry, 1 means the second to last).

--editor <command>

Specify an editor to use.

The editor can be specified by name (e.g. vim) or as a shell command, where %s is replaced with the file name (e.g. vim [options] %s).

This flag overrides the $EDITOR environment variable and the system.editor setting in the main configuration file.

--help | -h

Shows this help.

Editing

Content entries are in encoded text format.

The expected encoding for the file corresponds to the locale encoding. On most modern Unix systems this is UTF-8, but you can use the locale command in order to figure it out.

Each file starts with a header in YAML format. The header is followed by a line with three dashes (---) which marks the beginning of the actual content. The content will be parsed as Markdown when the site is compiled.

The header of a content entry is created automatically by pft edit when the accessed entry does not exist. The file gets then opened with a text editor. The $EDITOR environment variable will be honored unless an editor is defined in the pft.yaml configuration file (see the manual of pft init for further information). You may also specify a different editor using the --editor command line option.

After the editor is closed a warning will be issued if the header is invalid. If the file completely empty (as in zero bytes) it will be removed from the filesystem. If the header is valid but it is not consistent with the position in the filesystem (e.g. the date was manually changed) the file position is updated to be consistent.

The content header

Upon compilation the content text is parsed as Markdown and gets translated into HTML (see the manual of pft make for additional details). In this phase some special symbols are recognized: HTML tags such as <a> and <img> are analyzed in search of links to internal resources, like pictures or other pages within your PFT site.

This section contains a reference manual for the recognized special links. Since Markdown is a super-set of HTML, direct HTML can be supplied in the text too, so both Markdown and HTML syntaxes will be mentioned in the following description.

The recognized syntax for special links is:

:kind:param/param/...

Follows a list of valid kind keywords. The meaning of each param depends on the specified kind. Separation is done with the / symbol.

Pictures with :pic:path/to/picture.jpg

Picture reference accept special links in the form

![alttext](:pic:filename)
<img alt="alttext" src=":pic:filename"/>

This form will be resolved to an HTML link towards a file named named filename under the ROOT/content/pics directory. The name provided is used directly for lookup, so it must be complete of file extension, if any. The / symbol will work as path separator regardless of the operating system.

HTML Example:

<!-- ROOT/content/pics/test.png -->
<img src=":pic:test.png"/>

Markdown Example:

<!-- ROOT/content/pics/cars/golf.png -->
![](:pic:cars/golf.png)

URLs:

Regular URLs in <a> tags accept the following special prefixes:

:page:pagename

Resolve the link as the page having identified by pagename.

:blog:date/yy/mm/dd/slug

Resolve the link as the blog entry published at date yy/mm/dd and having the slug slug.

The slug parameter is optional if only one entry was published in the given date. The keyword date can be shortened as d.

:blog:back/N

Only valid within a blog entry. The generated link refers to N + 1 blog entries before the current one. The N parameter is optional, and defaults to zero (i.e. previous entry).

Examples:

<a href=":blog:back/0">     (previous entry)

<a href=":blog:back">       (equivalently, previous entry)

<a href=":blog:back/1">     (before previous, two entries ago)

<a href=":blog:back/5">     (six entries ago)
:web:service/param/param/...

Generate an URL which points to a web site or service (e.g. search engines, or specialized website) and passes data on the query. A number of valid values are supported for the service argument. The list of param arguments depend on the specific service.

Supported services:

Duck Duck Go

:web:ddg/bang/param/param/...

Search query on the Duck Duck Go search engine. The first parameter is used for Duck Duck Go's Bang syntax, and can be empty in order not to use any Bang.

Example: search linux howto on Duck Duck Go:

:web:ddg//linux/howto

Example: search linux howto with the !yt bang (redirects search on YouTube):

:web:ddg/yt/linux/howto

Example: search linux howto with the !so bang (redirects search on StackOverflow):

:web:ddg/so/linux/howto
Manpages

:web:man/name

:web:man/name/section

Point to an online Unix manual page. Manual section can be optionally supplied.

Examples:

:web:man/bash

:web:man/signal/7

Examples

Blog about today:

pft edit -B

Remove the page garbage

pft edit --editor ':> %s' -P garbage