1PFT-EDIT(1) User Contributed Perl Documentation PFT-EDIT(1)
2
3
4
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
21 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
26 There can be different kind of entries:
27
28 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
33 For example, a page entitled Hello World is stored as:
34
35 ROOT/content/pages/hello-world
36
37 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
45 For example, an entry entitled Hello World edited the 12th of
46 September 2015 is stored as:
47
48 ROOT/content/blog/2015-09/12-hello-world
49
50 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
57 For example, the month page for September 2015 is stored as:
58
59 ROOT/content/blog/2016-09.month
60
61 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
65 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
71 Tag pages are stored in "ROOT/content/tags", and their file name
72 depends on the tag title.
73
74 For example, a page containing a description of the tag chicken is
75 stored as:
76
77 ROOT/content/tags/chicken
78
80 -P Edit a page
81
82 A title is mandatory.
83
84 -B Edit a blog page
85
86 If no title is specified, it defaults to "today".
87
88 -M Edit a month page
89
90 The title is optional.
91
92 -T Edit a tag page
93
94 A title is mandatory.
95
96 --year=y | -y y
97 Defines a year for the edited entry. Implies -B unless -M is set.
98
99 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
103 --month=m | -m m
104 Defines a month for the edited entry. Implies -B unless -M is set.
105
106 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
110 --day=d | -d d
111 Defines a day for the edited entry. Implies -B unless -M is set.
112
113 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
117 --author=name | -a name
118 Defines the author for the entry.
119
120 This flag gets honored only when generating a header for the entry,
121 that is if the file does not exist yet.
122
123 --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
127 --resume | -r
128 Resume editing of a blog entry.
129
130 This option implies -B. The blog entry resumed for editing
131 corresponds by default to the latest in chronological order.
132
133 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
138 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
142 --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
148 --editor command
149 Specify an editor to use.
150
151 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
155 This flag overrides the $EDITOR environment variable and the
156 "system.editor" setting in the main configuration file.
157
158 This option is ignored if --stdin is used.
159
160 --stdin
161 Retrieve content from stdin.
162
163 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
171 If this option is in use the --editor is ignored.
172
173 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
177 --append
178 As for --stdin, but append content instead of replacing it.
179
180 If the content file does not exist or is empty, and header will be
181 automatically defined depending on the given command options.
182
183 If the header exists but is corrupted, the command will issue a
184 warning. No corrective action will be taken.
185
186 --select=id
187 Select a certain entry by index, in case of ambiguity.
188
189 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
195 --raw
196 This option is useful only if --stdin or --append are specified.
197
198 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
204 --help | -h
205 Shows this help.
206
207 Editing
208 Content entries are in encoded text format.
209
210 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
214 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
219 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
226 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
233 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
238 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
243 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
249 Options
250 Some optional properties of the entry:
251
252 hide
253 This feature is currently broken.
254
255 If set to 1 the entry is not going to be built by pft-make(1).
256
257 The intention is to temporarily hide an entry (e.g. if it is
258 incomplete).
259
260 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
266 Slug
267 The slug determines how the published file will be named.
268
269 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
273 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
277 Tags
278 A list of tags for the entry.
279
280 Tags can be specified one per line with a leading "-":
281
282 Tags:
283 - chicken
284 - tomato
285
286 Title
287 The title of the entry, in human readable form.
288
289 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
294 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
299 Links in the special syntax are in the form
300
301 :kind:param/param/...
302
303 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
307 Pictures with ":pic:path/to/picture.jpg"
308
309 Picture references accept special links in the Markdown form
310
311 ![alttext](:pic:filename)
312
313 or in the HTML form
314
315 <img alt="alttext" src=":pic:filename"/>
316
317 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
321 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
326 HTML Example:
327
328 <!-- ROOT/content/pics/test.png -->
329 <img src=":pic:test.png"/>
330
331 Markdown Example:
332
333 <!-- ROOT/content/pics/cars/golf.png -->
334 ![](:pic:cars/golf.png)
335
336 URLs:
337
338 Regular URLs in "<a>" tags accept the following special prefixes:
339
340 :page:pagename
341 Resolve the link as the page having identified by "pagename".
342
343 :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
347 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
350 :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
355 Examples:
356
357 <a href=":blog:back/0"> (previous entry)
358
359 <a href=":blog:back"> (equivalently, previous entry)
360
361 <a href=":blog:back/1"> (before previous, two entries ago)
362
363 <a href=":blog:back/5"> (six entries ago)
364
365 :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
369 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
373 Supported services:
374
375 Duck Duck Go
376 ":web:ddg/bang/param/param/..."
377
378 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
382 Example: search "linux howto" on Duck Duck Go:
383
384 :web:ddg//linux/howto
385
386 Example: search "linux howto" with the "!yt" bang (redirects
387 search on YouTube):
388
389 :web:ddg/yt/linux/howto
390
391 Example: search "linux howto" with the "!so" bang (redirects
392 search on StackOverflow):
393
394 :web:ddg/so/linux/howto
395
396 Manpages
397 ":web:man/name"
398
399 ":web:man/name/section"
400
401 Point to an online Unix manual page. Manual section can be
402 optionally supplied.
403
404 Examples:
405
406 :web:man/bash
407
408 :web:man/signal/7
409
410 Examples
411 Blog about today:
412
413 pft edit -B
414
415 Blog about today specifying a title
416
417 pft edit -B A lucky day
418
419 Remove the page "garbage"
420
421 pft edit --editor ':> %s' -P garbage
422
423 Resume the blog entry of the 27th of August 2014
424
425 pft edit -B -r -y2014 -d27 -m Aug
426
428 pft-init(1), pft-make(1)
429
430
431
432perl v5.30.0 2019-07-25 PFT-EDIT(1)