1PFT-EDIT(1)           User Contributed Perl Documentation          PFT-EDIT(1)
2
3
4

NAME

6       pft edit - Edit an entry
7

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

SEE ALSO

428       pft-init(1), pft-make(1)
429
430
431
432perl v5.36.0                      2022-07-22                       PFT-EDIT(1)
Impressum