pft-edit - Man Page

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

The pft-edit(1) command allows to conveniently edit a text entry in a PFT site. It takes care of creating a header for the new entries, to position files correctly within your PFT filesystem tree, and to maintain the filesystem location consistent depending on 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 text file encoded as by locale, composed by a YAML header concatenated with Markdown text (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 the page title.

For example, a page entitled Hello World is stored as:

    ROOT/content/pages/hello-world

Blog pages

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

For example, an entry entitled Hello World edited the 12th of September 2015 is stored as:

    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 * character). They are stored as ROOT/content/blog/YYYY-MM.month (where YYYY and MM represent the declared year and month).

For example, the month page for September 2015 is stored as:

    ROOT/content/blog/2016-09.month

Tag pages

All pages can optionally declare one or more tags. A tag in turn can be optionally 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 does not know).

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

For example, a page containing a description of the tag chicken is stored as:

    ROOT/content/tags/chicken

-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 of a blog entry.

This option implies -B. The blog entry resumed for editing corresponds by default to the latest in chronological order.

A date can be specified via the -y, -m and -d options. If the date is only partially specified, that is not all of -y, -m and -d are provided, the missing bits get completed with the current date.  If no date is specified, -r is equivalent to --back 0.

If more then one entry exists for the specified date, the command fails and the user is explicitly required to specify a selection via the --select option.

--back=count | -b count

Resume editing an old entry. The supplied parameter defines how many days we should go back in history since the last day we have an entry for (0 means the most recent day, 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.

This option is ignored if --stdin is used.

--stdin

Retrieve content from stdin.

The content file is selected according to the given options, and the content is retrieved from standard input.  If the file does exist it gets created with a reasonable header. If the file exists but the header is corrupted, the whole file gets replaced.  If the file exists and the header is well formed, the header is maintained and the remaining part of the file is replaced with content retrieved from standard input.

If this option is in use the --editor is ignored.

This editing mode handles input and output encoding according to the current locale, under the assumption that your content is text data.

--append

As for --stdin, but append content instead of replacing it.

If the content file does not exist or is empty, and header will be automatically defined depending on the given command options.

If the header exists but is corrupted, the command will issue a warning. No corrective action will be taken.

--select=id

Select a certain entry by index, in case of ambiguity.

This option applies when multiple files are matching the parameters for file selection, and a choice is required.  In these situations, if --select is not provided the pft-edit(1) command will fail, and the use of --select will be explicitly requested by an error message.

--raw

This option is useful only if --stdin or --append are specified.

If the --raw option is used the header is not maintained: pft edit --stdin --raw command will behave like cat > $content_file, while pft edit --append --raw will behave like cat >> $content_file. The path of $content_file is determined by the previously described file naming rules.

--help | -h

Shows this help.

    :kind:param/param/...

    ![alttext](:pic:filename)

    <img alt="alttext" src=":pic:filename"/>

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

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

    pft edit -B

    pft edit -B A lucky day

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

    pft edit -B -r -y2014 -d27 -m Aug

pft-init(1), pft-make(1)

pft(1), pft-init(1).