1PFT-EDIT(1) User Contributed Perl Documentation PFT-EDIT(1)
2
6 pft edit - Edit an entry
7
9 pft edit -P [options] title of your page
10 pft edit -B [options] title of your blog page
11 pft edit -M [options] title of your month page
12 pft edit -T [options] title of your tag page
13
15 The "pft edit" command allows to conveniently edit a text entry in a
16 PFT site. It takes care of creating a skeleton for the new entries, to
17 position them correctly within your PFT site, and to maintain their
18 position consistent with the type of content.
19 All entries are stored under the "ROOT/content" directory, where "ROOT"
21 is the base path of your PFT site. Each entry has the same format: a
22 text file encoded as by locale, composed by a YAML header concatenated
23 with Markdown text (more details later in this document).
24 There can be different kind of entries:
26 Regular Pages
28 Regular pages do not declare a date in their header. They get
29 positioned in "ROOT/content/pages". Their file name depends on
30 their title.
31 Example: a page entitled Hello World gets
33 ROOT/content/pages/hello-world
35 Blog pages
37 Blog pages declare a full date (year, month and day) in their
38 header. They get positioned in the "ROOT/content/blog/YYYY-MM"
39 directory (where "YYYY" and "MM" correspond to the declared year
40 and month respectively). Their file name starts with a "DD-"
41 prefix, where "DD" corresponds to the declared day. The remaining
42 part of the file name depends on their title.
43 Example: an entry entitled Hello World edited the 12th of September
45 2015 gets
46 ROOT/content/blog/2015-09/12-hello-world
48 Month pages
50 Month pages are meant as "entries summarizing a whole month". They
51 are like blog pages, but the date defined in their headers lack of
52 the day part (it is replaced by "*"). They are stored as
53 "ROOT/content/blog/YYYY-MM.month" (where "YYYY" and "MM" represent
54 the declared year and month).
55 Example: the month page for September 2015 gets
57 ROOT/content/blog/2016-09.month
59 Tag pages
61 All pages can optionally declare one or more tags. A tag can
62 optionally be associated to a tag page.
63 For example, if your site has have a number of entries about
65 cuisine, some of them might be tagged with the "chicken" tag. You
66 may want to have a tag page entitled "chicken", where you give a
67 description of what chicken is (just in case someone does not
68 know).
69 Tag pages are stored in "ROOT/content/tags", and their file name
71 depends on the tag title.
72 Example: a page containing a description of the tag chicken gets
74 ROOT/content/tags/chicken
76
78 -P Edit a page
79 A title is mandatory.
81 -B Edit a blog page
83 If no title is specified, it defaults to "today".
85 -M Edit a month page
87 The title is optional.
89 -T Edit a tag page
91 A title is mandatory.
93 --year=<y> | -y <y>
95 Defines a year for the edited entry. Implies -B unless -M is set.
96 This flag cannot be used if -P or -T are specified. It gets honored
98 only when generating a header for the entry, that is if the file
99 does not exist yet.
100 --month=<m> | -m <m>
102 Defines a month for the edited entry. Implies -B unless -M is set.
103 This flag cannot be used if -P or -T are specified. It gets honored
105 only when generating a header for the entry, that is if the file
106 does not exist yet.
107 --day=<d> | -d <d>
109 Defines a day for the edited entry. Implies -B unless -M is set.
110 This flag cannot be used if -P or -T are specified. It gets honored
112 only when generating a header for the entry, that is if the file
113 does not exist yet.
114 --author=<name> | -a <name>
116 Defines the author for the entry.
117 This flag gets honored only when generating a header for the entry,
119 that is if the file does not exist yet.
120 --tag=<tag> | -t <tag>
122 This flag gets honored only when generating a header for the entry,
123 that is if the file does not exist yet.
124 --resume | -r
126 Resume editing of a blog entry.
127 This option implies "-B". The blog entry resumed for editing
129 corresponds by default to the latest in chronological order.
130 A date can be specified via the "-y", "-m" and "-d" options. If the
132 date is only partially specified, that is not all of "-y", "-m" and
133 "-d" are provided, the missing bits get completed with the current
134 date. If no date is specified, "-r" is equivalent to "--back 0".
135 If more then one entry exists for the specified date, the command
137 fails and the user is explicitly required to specify a selection
138 via the "--select" option.
139 --back=<count> | -b <count>
141 Resume editing an old entry. The supplied parameter defines how
142 many days we should go back in history since the last day we have
143 an entry for (0 means the most recent day, 1 means the second to
144 last).
145 --editor <command>
147 Specify an editor to use.
148 The editor can be specified by name (e.g. "vim") or as a shell
150 command, where %s is replaced with the file name (e.g. "vim
151 [options] %s").
152 This flag overrides the $EDITOR environment variable and the
154 "system.editor" setting in the main configuration file.
155 --stdin
157 Retrieve content from stdin.
158 The content file is selected according to the given options, and
160 the content is retrieved from standard input. If the file does
161 exist it gets created with a reasonable header. If the file exists
162 but the header is corrupted, the whole file gets replaced. If the
163 file exists and the header is well formed, the header is maintained
164 and the remaining part of the file is replaced with content
165 retrieved from standard input.
166 If this option is in use the "--editor" gets ignored.
168 This mode handles input and output encoding according to the
170 current locale, under the assumption that your content is plain
171 text.
172 --append
174 As for "--stdin", but append content instead of replacing it.
175 If the content file does not exist or is empty it will be created
177 with a reasonable header. Otherwise the content will be appended to
178 it. If the header is corrupted the command will issue a warning,
179 but no further action will be taken.
180 --select=<id>
182 Select a certain entry by index, in case of ambiguity.
183 This option applies when multiple files are matching the parameters
185 for file selection, and a choice is required. In these situations,
186 if "--select" is not provided the "pft edit" command will fail, and
187 the use of "--select" will be explicitly requested by an error
188 message.
189 --raw
191 This option is useful only if "--stdin" or "--append" are
192 specified.
193 If the "--raw" option is used the header is not maintained:
195 "--stdin" will behave like the "cat > $content_file" unix command
196 line, and "--append" will behave like "cat >> $content_file".
197 --help | -h
199 Shows this help.
200 Editing
202 Content entries are in encoded text format.
203 The expected encoding for the file corresponds to the "locale"
205 encoding. On most modern Unix systems this is UTF-8, but you can use
206 the "locale" command in order to figure it out.
207 Each file starts with a header in YAML format. The header is followed
209 by a line with three dashes ("---") which marks the beginning of the
210 actual content. The content will be parsed as Markdown when the site is
211 compiled.
212 The header of a content entry is created automatically by "pft edit"
214 when the accessed entry does not exist. The file gets then opened with
215 a text editor. The $EDITOR environment variable will be honored unless
216 an editor is defined in the "pft.yaml" configuration file (see the
217 manual of "pft init" for further information). You may also specify a
218 different editor using the "--editor" command line option.
219 After the editor is closed a warning will be issued if the header is
221 invalid. If the file completely empty (as in zero bytes) it will be
222 removed from the filesystem. If the header is valid but it is not
223 consistent with the position in the filesystem (e.g. the date was
224 manually changed) the file position is updated to be consistent.
225 The content header
227 Each entry starts with a header in YAML format. The header defines the
228 properties of the entries. Valid properties with their descriptions
229 follow in this section.
230 Author
232 The author of the entry. Any string can be entered as value. The
233 default value of it is taken from the "pft.yaml" configuration
234 file.
235 Date
237 The date associated with the entry. This field is required only for
238 blog entries. Changing the value while editing with "pft edit" will
239 result to the position in the filesystem to be adapted
240 consistently.
241 Options
243 Some optional properties of the entry:
244 hide
246 If set to 1 the entry is going to be hidden.
247 This option is meant as a way to temporarily hide an entry.
249 Currently it is somewhat broken, so its use is not recommended.
250 template
252 Each page can specify a different template to use by means of
253 this field. It is by default defined as "~" (in YAML that is
254 null) meaning that the page will use the global template as
255 defined in the "pft.yaml" configuration file.
256 Slug
258 The slug determines how the file will be named.
259 By default it is derived by removing non-word characters from the
261 Title field. The purpose is having a reasonable file name, which is
262 both convenient and healty to handle with command line programs
263 (escape sequences get removed, etc).
264 Tags
266 A list of tags for the entry.
267 Tags can be specified one per line with a leading "-":
269 Tags:
271 - chicken
272 - tomato
273 Title
275 The title of the entry, in human readable form.
276 The content text
278 Upon compilation the content text is parsed as Markdown and gets
279 translated into HTML (see the manual of "pft make" for additional
280 details). In this phase some special symbols are recognized: HTML tags
281 such as "<a>" and "<img>" are analyzed in search of links to internal
282 resources, like pictures or other pages within your PFT site.
283 This section contains a reference manual for the recognized special
285 links. Since Markdown is a super-set of HTML, direct HTML can be
286 supplied in the text too, so both Markdown and HTML syntaxes will be
287 mentioned in the following description.
288 The recognized syntax for special links is:
290 :kind:param/param/...
292 Follows a list of valid "kind" keywords. The meaning of each "param"
294 depends on the specified "kind". Separation is done with the "/"
295 symbol.
296 Pictures with ":pic:path/to/picture.jpg"
298 Picture reference accept special links in the form
300 
302 <img alt="alttext" src=":pic:filename"/>
303 This form will be resolved to an HTML link towards a file named named
305 filename under the "ROOT/content/pics" directory. The name provided is
306 used directly for lookup, so it must be complete of file extension, if
307 any. The "/" symbol will work as path separator regardless of the
308 operating system.
309 HTML Example:
311 <!-- ROOT/content/pics/test.png -->
313 <img src=":pic:test.png"/>
314 Markdown Example:
316 <!-- ROOT/content/pics/cars/golf.png -->
318 
319 URLs:
321 Regular URLs in "<a>" tags accept the following special prefixes:
323 :page:pagename
325 Resolve the link as the page having identified by "pagename".
326 :blog:date/yy/mm/dd/slug
328 Resolve the link as the blog entry published at date yy/mm/dd and
329 having the slug slug.
330 The slug parameter is optional if only one entry was published in
332 the given date. The keyword "date" can be shortened as "d".
333 :blog:back/N
335 Only valid within a blog entry. The generated link refers to N + 1
336 blog entries before the current one. The N parameter is optional,
337 and defaults to zero (i.e. previous entry).
338 Examples:
340 <a href=":blog:back/0"> (previous entry)
342 <a href=":blog:back"> (equivalently, previous entry)
344 <a href=":blog:back/1"> (before previous, two entries ago)
346 <a href=":blog:back/5"> (six entries ago)
348 :web:service/param/param/...
350 Generate an URL which points to a web site or service (e.g. search
351 In all other cases the "--select" flag is silently ignored.
352 engines, or specialized website) and passes data on the query. A
354 number of valid values are supported for the service argument. The
355 list of param arguments depend on the specific service.
356 Supported services:
358 Duck Duck Go
360 ":web:ddg/bang/param/param/..."
361 Search query on the Duck Duck Go search engine. The first
363 parameter is used for Duck Duck Go's Bang syntax, and can be
364 empty in order not to use any Bang.
365 Example: search "linux howto" on Duck Duck Go:
367 :web:ddg//linux/howto
369 Example: search "linux howto" with the "!yt" bang (redirects
371 search on YouTube):
372 :web:ddg/yt/linux/howto
374 Example: search "linux howto" with the "!so" bang (redirects
376 search on StackOverflow):
377 :web:ddg/so/linux/howto
379 Manpages
381 ":web:man/name"
382 ":web:man/name/section"
384 Point to an online Unix manual page. Manual section can be
386 optionally supplied.
387 Examples:
389 :web:man/bash
391 :web:man/signal/7
393 Examples
395 Blog about today:
396 pft edit -B
398 Blog about today specifying a title
400 pft edit -B A lucky day
402 Remove the page "garbage"
404 pft edit --editor ':> %s' -P garbage
406 Resume the blog entry of the 27th of August 2014
408 pft edit -B -r -y2014 -d27 -m Aug
410perl v5.28.1 2017-09-25 PFT-EDIT(1)