1PFT-EDIT(1) User Contributed Perl Documentation PFT-EDIT(1)
2
6 pft edit - Edit an entry
7
9 B<pft edit -P> [options] title of your page
10 B<pft edit -B> [options] title of your blog page
11 B<pft edit -M> [options] title of your month page
12 B<pft edit -T> [options] title of your tag page
13
15 The pft-edit(1) command allows to conveniently edit a text entry in a
16 PFT site. It takes care of creating a header for the new entries, to
17 position files correctly within your PFT filesystem tree, and to
18 maintain the filesystem location consistent depending on the type of
19 content.
20 All entries are stored under the "ROOT/content" directory, where "ROOT"
22 is the base path of your PFT site. Each entry has the same format: a
23 text file encoded as by locale, composed by a YAML header concatenated
24 with Markdown text (more details later in this document).
25 There can be different kind of entries:
27 Regular Pages
29 Regular pages do not declare a date in their header. They get
30 positioned in "ROOT/content/pages". Their file name depends on the
31 page title.
32 For example, a page entitled Hello World is stored as:
34 ROOT/content/pages/hello-world
36 Blog pages
38 Blog pages declare a full date (year, month and day) in their
39 header. They are positioned in the "ROOT/content/blog/YYYY-MM"
40 directory (where "YYYY" and "MM" correspond to the declared year
41 and month, respectively). The file name of a blog page starts with
42 a "DD-" prefix, where "DD" corresponds to the declared day. The
43 remaining part of the file name depends on the entry title.
44 For example, an entry entitled Hello World edited the 12th of
46 September 2015 is stored as:
47 ROOT/content/blog/2015-09/12-hello-world
49 Month pages
51 Month pages are meant as entries summarizing a whole month. They
52 are like blog pages, but the date defined in their headers lack of
53 the day part (it is replaced by "*" character). They are stored as
54 "ROOT/content/blog/YYYY-MM.month" (where "YYYY" and "MM" represent
55 the declared year and month).
56 For example, the month page for September 2015 is stored as:
58 ROOT/content/blog/2016-09.month
60 Tag pages
62 All pages can optionally declare one or more tags. A tag in turn
63 can be optionally associated to a tag page.
64 For example, if your site has have a number of entries about
66 cuisine, some of them might be tagged with the "chicken" tag. You
67 may want to have a tag page entitled "chicken", where you give a
68 description of what chicken is (just in case someone does not
69 know).
70 Tag pages are stored in "ROOT/content/tags", and their file name
72 depends on the tag title.
73 For example, a page containing a description of the tag chicken is
75 stored as:
76 ROOT/content/tags/chicken
78
80 -P Edit a page
81 A title is mandatory.
83 -B Edit a blog page
85 If no title is specified, it defaults to "today".
87 -M Edit a month page
89 The title is optional.
91 -T Edit a tag page
93 A title is mandatory.
95 --year=y | -y y
97 Defines a year for the edited entry. Implies -B unless -M is set.
98 This flag cannot be used if -P or -T are specified. It gets honored
100 only when generating a header for the entry, that is if the file
101 does not exist yet.
102 --month=m | -m m
104 Defines a month for the edited entry. Implies -B unless -M is set.
105 This flag cannot be used if -P or -T are specified. It gets honored
107 only when generating a header for the entry, that is if the file
108 does not exist yet.
109 --day=d | -d d
111 Defines a day for the edited entry. Implies -B unless -M is set.
112 This flag cannot be used if -P or -T are specified. It gets honored
114 only when generating a header for the entry, that is if the file
115 does not exist yet.
116 --author=name | -a name
118 Defines the author for the entry.
119 This flag gets honored only when generating a header for the entry,
121 that is if the file does not exist yet.
122 --tag=tag | -t tag
124 This flag gets honored only when generating a header for the entry,
125 that is if the file does not exist yet.
126 --resume | -r
128 Resume editing of a blog entry.
129 This option implies -B. The blog entry resumed for editing
131 corresponds by default to the latest in chronological order.
132 A date can be specified via the -y, -m and -d options. If the date
134 is only partially specified, that is not all of -y, -m and -d are
135 provided, the missing bits get completed with the current date. If
136 no date is specified, -r is equivalent to --back 0.
137 If more then one entry exists for the specified date, the command
139 fails and the user is explicitly required to specify a selection
140 via the --select option.
141 --back=count | -b count
143 Resume editing an old entry. The supplied parameter defines how
144 many days we should go back in history since the last day we have
145 an entry for (0 means the most recent day, 1 means the second to
146 last).
147 --editor command
149 Specify an editor to use.
150 The editor can be specified by name (e.g. "vim") or as a shell
152 command, where %s is replaced with the file name (e.g. "vim
153 [options] %s").
154 This flag overrides the $EDITOR environment variable and the
156 "system.editor" setting in the main configuration file.
157 This option is ignored if --stdin is used.
159 --stdin
161 Retrieve content from stdin.
162 The content file is selected according to the given options, and
164 the content is retrieved from standard input. If the file does
165 exist it gets created with a reasonable header. If the file exists
166 but the header is corrupted, the whole file gets replaced. If the
167 file exists and the header is well formed, the header is maintained
168 and the remaining part of the file is replaced with content
169 retrieved from standard input.
170 If this option is in use the --editor is ignored.
172 This editing mode handles input and output encoding according to
174 the current locale, under the assumption that your content is text
175 data.
176 --append
178 As for --stdin, but append content instead of replacing it.
179 If the content file does not exist or is empty, and header will be
181 automatically defined depending on the given command options.
182 If the header exists but is corrupted, the command will issue a
184 warning. No corrective action will be taken.
185 --select=id
187 Select a certain entry by index, in case of ambiguity.
188 This option applies when multiple files are matching the parameters
190 for file selection, and a choice is required. In these situations,
191 if --select is not provided the pft-edit(1) command will fail, and
192 the use of --select will be explicitly requested by an error
193 message.
194 --raw
196 This option is useful only if --stdin or --append are specified.
197 If the --raw option is used the header is not maintained: "pft edit
199 --stdin --raw" command will behave like "cat > $content_file",
200 while "pft edit --append --raw" will behave like "cat >>
201 $content_file". The path of $content_file is determined by the
202 previously described file naming rules.
203 --help | -h
205 Shows this help.
206 Editing
208 Content entries are in encoded text format.
209 The expected encoding for the file corresponds to the "locale". On
211 modern systems UTF-8 is the more popular encoding, but you can use the
212 locale(1) command to figure out.
213 Each file starts with a header in YAML format. The header is followed
215 by a line with three dashes ("---") which marks the beginning of the
216 actual content. The content will be parsed as Markdown when the site is
217 compiled.
218 The header of a content entry is created automatically by pft-edit(1)
220 when the accessed entry does not exist. The file gets then opened with
221 a text editor. The $EDITOR environment variable will be honored unless
222 an editor is defined in the "pft.yaml" configuration file (see
223 pft-init(1)). You may also specify a different editor using the
224 --editor command line option.
225 When the editor is terminated the file content is evaluated. A warning
227 will be issued if the header is invalid. If the file completely empty
228 (zero bytes) it will be removed from the filesystem. If the header is
229 valid but not consistent with the position in the filesystem (e.g. the
230 date was manually changed) the file position is updated according to
231 the header.
232 The content header
234 Each entry starts with a header in YAML format. The header defines the
235 properties of the entries. Valid properties with their descriptions
236 follow in this section.
237 Author
239 The author of the entry. Any string can be entered as value. The
240 default value of it is taken from the "pft.yaml" configuration
241 file.
242 Date
244 The date associated with the entry. This field is required only for
245 blog entries. Changing the value while editing with pft-edit(1)
246 will result to the position in the filesystem to be adapted
247 consistently.
248 Options
250 Some optional properties of the entry:
251 hide
253 This feature is currently broken.
254 If set to 1 the entry is not going to be built by pft-make(1).
256 The intention is to temporarily hide an entry (e.g. if it is
258 incomplete).
259 template
261 Each page can specify a different template to use by means of
262 this field. It is by default defined as "~" (in YAML that is
263 null) meaning that the page will use the global template as
264 defined in the "pft.yaml" configuration file.
265 Slug
267 The slug determines how the published file will be named.
268 The default slug value is derived by removing non-word characters
270 from the Title field. The purpose is to have a mnemonic file name,
271 which is both readable and convenient to handle.
272 The field can be manually changed in the header, and this will
274 result in the file name to be modified when the editor is
275 terminated.
276 Tags
278 A list of tags for the entry.
279 Tags can be specified one per line with a leading "-":
281 Tags:
283 - chicken
284 - tomato
285 Title
287 The title of the entry, in human readable form.
288 Links in content
290 Besides regular URLs, internal resources such as pages, blog entries
291 and imported images can be referenced by means of a special link
292 syntax.
293 Upon compilation by pft-make(1) the content is translated from Markdown
295 to HTML. After this phase HTML elements such as "<a>" and "<img>" are
296 scanned, and those links matching the special syntax are resolved
297 according to the rules described in this manual.
298 Links in the special syntax are in the form
300 :kind:param/param/...
302 There is a number of accepted "kind" keywords. The number and meaning
304 of each parameter "param" depends on the specified "kind". The slash
305 ("/") symbol separates syntactically the various parameters.
306 Pictures with ":pic:path/to/picture.jpg"
308 Picture references accept special links in the Markdown form
310 
312 or in the HTML form
314 <img alt="alttext" src=":pic:filename"/>
316 A link like this will be resolved to a file named named filename under
318 the "ROOT/content/pics" directory. The name provided is used directly
319 for lookup, so it must be complete of file extension, if any.
320 The "img" keyword allows for an arbitrary number of parameter, each of
322 which concurs to define the path of the picture. In other words, the
323 "/" symbol will work as path separator regardless of the operating
324 system.
325 HTML Example:
327 <!-- ROOT/content/pics/test.png -->
329 <img src=":pic:test.png"/>
330 Markdown Example:
332 <!-- ROOT/content/pics/cars/golf.png -->
334 
335 URLs:
337 Regular URLs in "<a>" tags accept the following special prefixes:
339 :page:pagename
341 Resolve the link as the page having identified by "pagename".
342 :blog:date/yy/mm/dd/slug
344 Resolve the link as the blog entry published at date yy/mm/dd and
345 having the slug slug.
346 The slug parameter is optional if only one entry was published in
348 the given date. The keyword "date" can be shortened as "d".
349 :blog:back/N
351 Only valid within a blog entry. The generated link refers to N + 1
352 blog entries before the current one. The N parameter is optional,
353 and defaults to zero (i.e. previous entry).
354 Examples:
356 <a href=":blog:back/0"> (previous entry)
358 <a href=":blog:back"> (equivalently, previous entry)
360 <a href=":blog:back/1"> (before previous, two entries ago)
362 <a href=":blog:back/5"> (six entries ago)
364 :web:service/param/param/...
366 Generate an URL which points to a web site or service (e.g. search
367 In all other cases the --select flag is silently ignored.
368 engines, or specialized website) and passes data on the query. A
370 number of valid values are supported for the service argument. The
371 list of param arguments depend on the specific service.
372 Supported services:
374 Duck Duck Go
376 ":web:ddg/bang/param/param/..."
377 Search query on the Duck Duck Go search engine. The first
379 parameter is used for Duck Duck Go's Bang syntax, and can be
380 empty in order not to use any Bang.
381 Example: search "linux howto" on Duck Duck Go:
383 :web:ddg//linux/howto
385 Example: search "linux howto" with the "!yt" bang (redirects
387 search on YouTube):
388 :web:ddg/yt/linux/howto
390 Example: search "linux howto" with the "!so" bang (redirects
392 search on StackOverflow):
393 :web:ddg/so/linux/howto
395 Manpages
397 ":web:man/name"
398 ":web:man/name/section"
400 Point to an online Unix manual page. Manual section can be
402 optionally supplied.
403 Examples:
405 :web:man/bash
407 :web:man/signal/7
409 Examples
411 Blog about today:
412 pft edit -B
414 Blog about today specifying a title
416 pft edit -B A lucky day
418 Remove the page "garbage"
420 pft edit --editor ':> %s' -P garbage
422 Resume the blog entry of the 27th of August 2014
424 pft edit -B -r -y2014 -d27 -m Aug
426
428 pft-init(1), pft-make(1)
429perl v5.38.0 2023-07-20 PFT-EDIT(1)