Browse Source

replace README.pod with README.md; remove Travis link

This no longer just duplicates the POD contents of lib/App/WRT.pm.

Also gets rid of the Travis CI widget.
Brennen Bearnes 1 month ago
parent
commit
8086354d2c
4 changed files with 81 additions and 473 deletions
  1. 4
    0
      Changes
  2. 74
    0
      README.md
  3. 0
    468
      README.pod
  4. 3
    5
      lib/App/WRT.pm

+ 4
- 0
Changes View File

@@ -1,5 +1,9 @@
1 1
 Revision history for App::WRT
2 2
 
3
+v6.2.4 2019-05-28
4
+
5
+  - Replace README.pod with a concise README.md
6
+
3 7
 v6.2.3 2019-05-16
4 8
 
5 9
   - bin/wrt-display: correctly expand new, fulltext, all

+ 74
- 0
README.md View File

@@ -0,0 +1,74 @@
1
+wrt
2
+===
3
+
4
+wrt (WRiting Tool) is a static site / blog generator and some related
5
+utilities.
6
+
7
+This project can be thought of as both a format for storing blog entries and
8
+other writing in folders and files, as well as the utilities for rendering them
9
+to a full-fledged web site.  It's particularly well-suited to collections of
10
+blog entries organized by date.
11
+
12
+wrt can be found at:
13
+
14
+  - [metacpan.org as App::WRT](https://metacpan.org/pod/App::WRT) - latest CPAN release
15
+  - https://code.p1k3.com/gitea/brennen/wrt - latest code
16
+
17
+I have been using some version of this code to publish
18
+[p1k3](https://p1k3.com/) since 2001, and have written [various posts about
19
+it](https://p1k3.com/topics/wrt/) over the years.
20
+
21
+installation and use
22
+====================
23
+
24
+You'll need a Unix / Linux, and a relatively recent Perl installation.  In
25
+practice I know that Debian Jessie or later (or Ubuntu 16.04 or later) and Perl
26
+5.26.1 work.
27
+
28
+The short version, git edition: 
29
+
30
+    $ git clone https://code.p1k3.com/gitea/brennen/wrt.git
31
+    $ cd wrt
32
+    $ perl Build.PL
33
+    $ ./Build installdeps
34
+    $ ./Build test
35
+    $ ./Build install
36
+
37
+The short version, CPAN edition:
38
+
39
+    $ cpan -i App::WRT
40
+
41
+Starting a new site once installed:
42
+
43
+    # Set up some defaults:
44
+    $ mkdir project && cd project
45
+    $ wrt init
46
+
47
+    # Edit an entry for January 1, 2019:
48
+    $ mkdir -p archives/2019/1/
49
+    $ nano archives/2019/1/1
50
+
51
+    # Publish HTML to project/public/
52
+    $ wrt render-all
53
+
54
+Please see the [App::WRT listing on MetaCPAN][mc] or the POD documentation in
55
+[lib/App/WRT.pm](lib/App/WRT.pm) in this repository for detailed instructions.
56
+
57
+[mc]: https://metacpan.org/pod/App::WRT
58
+
59
+copying
60
+=======
61
+
62
+wrt is copyright 2001-2019 Brennen Bearnes.
63
+
64
+wrt is free software; you can redistribute it and/or modify it under the terms
65
+of the GNU General Public License as published by the Free Software Foundation;
66
+either version 2 of the License, or (at your option) any later version.
67
+
68
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
69
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
70
+PARTICULAR PURPOSE.  See the GNU General Public License for more details.
71
+
72
+You should have received a copy of the GNU General Public License
73
+along with this program.  If not, see http://www.gnu.org/licenses/
74
+

+ 0
- 468
README.pod View File

@@ -1,468 +0,0 @@
1
-=pod
2
-
3
-=head1 NAME
4
-
5
-App::WRT - WRiting Tool, a static site/blog generator and related utilities
6
-
7
-=for HTML <a href="https://travis-ci.org/brennen/wrt"><img src="https://travis-ci.org/brennen/wrt.svg?branch=master"></a>
8
-
9
-=head1 SYNOPSIS
10
-
11
-Using the commandline tools:
12
-
13
-    $ mkdir project
14
-    $ cd project
15
-    $ wrt init         # set up some defaults
16
-    $ wrt config       # dump configuration values
17
-    $ wrt ls           # list entries
18
-    $ wrt display new  # print HTML for new entries to stdout
19
-    $ wrt render-all   # publish HTML to project/public/
20
-
21
-Using App::WRT in library form:
22
-
23
-    #!/usr/bin/env perl
24
-
25
-    use App::WRT;
26
-    my $w = App::WRT->new(
27
-      entry_dir => 'archives',
28
-      url_root  => '/',
29
-      # etc.
30
-    );
31
-    print $w->display(@ARGV);
32
-
33
-=head1 INSTALLING
34
-
35
-It's possible but not likely this would run on a Perl as old as 5.10.0.  In
36
-practice, I know that it works under 5.26.2.  It should be fine on any
37
-reasonably modern Linux distribution, and may work on MacOS or a BSD of your
38
-choosing.  It's possible that it would run under the Windows Subsystem for
39
-Linux, but it would definitely fail under vanilla Windows; it currently makes
40
-too many assumptions about things like directory path separators and filesystem
41
-semantics.
42
-
43
-(Although I would like the code to be more robust across platforms, this is not
44
-a problem I feel much urgency about solving at the moment, since I'm pretty
45
-sure I am the only user of this software.  Patches would certainly be welcome.)
46
-
47
-To install the latest development version from the main repo:
48
-
49
-    $ git clone https://code.p1k3.com/gitea/brennen/wrt.git
50
-    $ cd wrt
51
-    $ perl Build.PL
52
-    $ ./Build installdeps
53
-    $ ./Build test
54
-    $ ./Build install
55
-
56
-To install the latest version released on CPAN:
57
-
58
-    $ cpanm App::WRT
59
-
60
-Or:
61
-
62
-    $ cpan -i App::WRT
63
-
64
-You will likely need to use C<sudo> or C<su> to get a systemwide install.
65
-
66
-=head1 DESCRIPTION
67
-
68
-This started life somewhere around 2001 as C<display.pl>, a CGI script to
69
-concatenate fragments of handwritten HTML by date.  It has since accumulated
70
-several of the usual weblog features (lightweight markup, feed generation,
71
-embedded Perl, poetry tools, image galleries, and ill-advised dependencies),
72
-but the basic idea hasn't changed that much.
73
-
74
-The C<wrt> utility now generates static HTML files, instead of expecting to
75
-run as a CGI script.  This is a better idea, for the most part.
76
-
77
-By default, entries are stored in a simple directory tree under C<entry_dir>.
78
-
79
-Like:
80
-
81
-     archives/2001/1/1
82
-     archives/2001/1/2/index
83
-     archives/2001/1/2/sub_entry
84
-
85
-Which will publish files like so:
86
-
87
-     public/index.html
88
-     public/all/index.html
89
-     public/2001/index.html
90
-     public/2001/1/index.html
91
-     public/2001/1/1/index.html
92
-     public/2001/1/2/index.html
93
-     public/2001/1/2/sub_entry/index.html
94
-
95
-Contents will be generated for each year and for the entire collection of dated
96
-entries.  Month indices will consist of all entries for that month.  A
97
-top-level index file will consist of the most recent month's entries.
98
-
99
-It's possible (although not as flexible as it ought to be) to redefine the
100
-directory layout.  (See C<%default{entry_map}> below.)
101
-
102
-An entry may be either a plain UTF-8 text file, or a directory containing
103
-several such files.  If it's a directory, a file named "index" will be treated
104
-as the text of the entry, and all other lower-case filenames without extensions
105
-will be treated as sub-entries or documents within that entry, and displayed
106
-accordingly.  Links to certain other filetypes will be displayed as well.
107
-
108
-Directories may be nested to an arbitrary depth, although it's probably not a
109
-good idea to go very deep with the current display logic.
110
-
111
-A PNG or JPEG file with a name like
112
-
113
-    2001/1/1.icon.png
114
-    2001/1/1/index.icon.png
115
-    2001/1/1/whatever.icon.png
116
-    2001/1/1/whatever/index.icon.png
117
-
118
-will be treated as an icon for the corresponding entry file.
119
-
120
-=head2 MARKUP
121
-
122
-Entries may consist of hand-written HTML (to be passed along without further
123
-interpretation), a supported form of lightweight markup, or some combination
124
-thereof. Actually, an entry may consist of any darn thing you please, as long
125
-as Perl will agree that it is text, but presumably you're going to be feeding
126
-this to a browser.
127
-
128
-Header tags (<h1>, <h2>, etc.) will be used to display titles in feeds and
129
-other places.
130
-
131
-Other special markup is indicated by a variety of HTML-like container tags.
132
-
133
-B<Embedded Perl> - evaluated and replaced by whatever value you return
134
-(evaluated in a scalar context):
135
-
136
-     <perl>my $dog = "Ralph."; return $dog;</perl>
137
-
138
-This code is evaluated before any other processing is done, so you can return
139
-any other markup understood by the script and have it handled appropriately.
140
-
141
-B<Interpolated variables> - actually keys to the hash underlying the App::WRT
142
-object, for the moment:
143
-
144
-     <perl>$self->{title} = "About Ralph, My Dog"; return '';</perl>
145
-
146
-     <p>The title is <em>${title}</em>.</p>
147
-
148
-This is likely to change at some point, so don't build anything too elaborate
149
-on it.
150
-
151
-Embedded code and variables are intended only for use in the F<template> file,
152
-where it's handy to drop in titles or conditionalize aspects of a layout. You
153
-want to be careful with this sort of thing - it's useful in small doses, but
154
-it's also a maintainability nightmare waiting to happen.
155
-
156
-B<Includes> - replaced by the contents of the enclosed file path, from the
157
-root of the current wrt project:
158
-
159
-    <include>path/to/file</include>
160
-
161
-This is a bit constraining, since it doesn't currently allow for files outside
162
-of the current project, but is useful for including HTML generated by an
163
-external script in a page.
164
-
165
-B<Several forms of lightweight markup>:
166
-
167
-     <markdown>John Gruber's Markdown, by way of
168
-     Text::Markdown::Discount</markdown>
169
-
170
-     <textile>Dean Allen's Textile, via Brad Choate's
171
-     Text::Textile.</textile>
172
-
173
-     <freeverse>An easy way to
174
-     get properly broken lines
175
-     plus -- em dashes --
176
-     for poetry and such.</freeverse>
177
-
178
-B<And a couple of shortcuts>:
179
-
180
-     <image>filename.ext
181
-     alt text, if any</image>
182
-
183
-     <list>
184
-     one list item
185
-
186
-     another list item
187
-     </list>
188
-
189
-As it stands, freeverse, image, and list are not particularly robust.
190
-
191
-=head2 TEMPLATES
192
-
193
-A single template, specified by the C<template_dir> and C<template> config
194
-values, is used to render all pages.  See F<example/templates/basic> for an
195
-example, or run C<wrt init> in an empty directory and look at
196
-F<templates/default>.
197
-
198
-Here's a short example:
199
-
200
-    <!DOCTYPE html>
201
-    <html>
202
-    <head>
203
-      <meta charset="UTF-8">
204
-      <title>${title_prefix} - ${title}</title>
205
-    </head>
206
-
207
-    <body>
208
-    ${content}
209
-    </body>
210
-
211
-    </html>
212
-
213
-Within templates, C<${foo}> will be replaced with the corresponding
214
-configuration value.  C<${content}> will always be set to the content of the
215
-current entry.
216
-
217
-=head2 CONFIGURATION
218
-
219
-Configuration is read from a F<wrt.json> in the directory where the C<wrt>
220
-utility is invoked, or can (usually) be specified with the C<--config> option.
221
-
222
-See F<example/wrt.json> for a sample configuration.
223
-
224
-Under the hood, configuration is done by combining a hash called C<%default>
225
-with values pulled out of the JSON file.  Most defaults can be overwritten
226
-from the config file, but changing some would require writing Perl, since
227
-they contain things like subroutine references.
228
-
229
-=over
230
-
231
-=item %default
232
-
233
-Here's a verbatim copy of C<%default>, with some commentary about values.
234
-
235
-    my %default = (
236
-      root_dir       => '.',         # dir for wrt repository
237
-      entry_dir      => 'archives',  # dir for entry files
238
-      publish_dir    => 'public',    # dir to publish site to
239
-      url_root       => "/",         # root URL for building links
240
-      image_url_root => '',          # same for images
241
-      template_dir   => 'templates', # dir for template files
242
-      template       => 'default',   # template to use
243
-      title          => '',          # current title (used in template)
244
-      title_prefix   => '',          # a string to slap in front of titles
245
-      stylesheet_url => undef,       # path to a CSS file (used in template)
246
-      favicon_url    => undef,       # path to a favicon (used in template)
247
-      feed_alias     => 'feed',      # what entry path should correspond to feed?
248
-      feed_length    => 30,          # how many entries should there be in the feed?
249
-      author         => undef,       # author name (used in template, feed)
250
-      description    => undef,       # site description (used in template)
251
-      content        => undef,       # place to stash content for templates
252
-      embedded_perl  => 1,           # evaluate embedded <perl> tags?
253
-      default_entry  => 'new',       # what to display if no entry specified
254
-      cache_includes => 0,           # should included files be cached in memory?
255
-
256
-      # A license string for site content:
257
-      license        => 'public domain',
258
-
259
-      # A string value to replace all pages with (useful for occasional
260
-      # situations where every page of a site should serve some other
261
-      # content in-place, like Net Neutrality protest blackouts):
262
-      overlay        => undef,
263
-
264
-      # What gets considered an entry _path_:
265
-      entrypath_expr => qr/^ ([a-z0-9_\/-]+) $/x,
266
-
267
-      # What gets considered a subentry file (slightly misleading
268
-      # terminology here):
269
-      subentry_expr => qr/^[0-9a-z_-]+(\.(tgz|zip|tar[.]gz|gz|txt))?$/,
270
-
271
-      # We'll show links for these, but not display them inline:
272
-      binfile_expr   => qr/[.](tgz|zip|tar[.]gz|gz|txt|pdf)$/,
273
-    );
274
-
275
-=item $default{entry_map}
276
-
277
-A hashref which will dispatch entries matching various regexen to the
278
-appropriate output methods. The default looks something like this:
279
-
280
-    nnnn/[nn/nn/]doc_name - a document within a day.
281
-    nnnn/nn/nn            - a specific day.
282
-    nnnn/nn               - a month.
283
-    nnnn                  - a year.
284
-    doc_name              - a document in the root directory.
285
-
286
-You can re-map things to an arbitrary archive layout.
287
-
288
-Since the entry map is a hash, and handle() simply loops over its keys, there
289
-is no guaranteed precedence of patterns. Be extremely careful that no entry
290
-will match more than one pattern, or you will wind up with unexpected behavior.
291
-A good way to ensure that this does not happen is to use patterns like:
292
-
293
-    qr(
294
-        ^           # start of string
295
-        [0-9/]{4}/  # year
296
-        [0-9]{1,2}/ # month
297
-        [0-9]{1,2]  # day
298
-        $           # end of string
299
-      )x
300
-
301
-...always marking the start and end of the string explicitly.
302
-
303
-This may eventually be rewritten to use an array so that the order can be
304
-explicitly specified.
305
-
306
-=item $default{entry_descriptions}
307
-
308
-A hashref which contains a map of entry titles to entry descriptions.
309
-
310
-=item $default{title_cache}
311
-
312
-A hashref which contains a cache of entry titles, populated by the renderer.
313
-
314
-=back
315
-
316
-=head2 METHODS AND INTERNALS
317
-
318
-For no bigger than this thing is, the internals are convoluted.  (This is
319
-because it's spaghetti code originally written in a now-archaic language by a
320
-teenager who didn't know how to program.)
321
-
322
-=over
323
-
324
-=item new_from_file($config_file)
325
-
326
-Takes a filename to pull JSON config data out of, and returns a new App::WRT
327
-instance with the parameters set in that file.
328
-
329
-=item new(%params)
330
-
331
-Get a new WRT object with the specified parameters set.
332
-
333
-=item display($entry1, $entry2, ...)
334
-
335
-Return a string containing the given entries, which are in the form of
336
-date/entry strings. If no parameters are given, default to default_entry().
337
-
338
-display() expands aliases ("new" and "all", for example) as necessary, collects
339
-output from handle($entry), and wraps the whole thing in a template file.
340
-
341
-If C<overlay> is set, will return the value of overlay regardless of options.
342
-(This is useful for hackily replacing every page in a site with a single blob
343
-of HTML, for example if you're participating in some sort of blackout or
344
-something.)
345
-
346
-=item handle($entry)
347
-
348
-Return the text of an individual entry.
349
-
350
-=item expand_alias($option)
351
-
352
-Expands/converts 'all', 'new', and 'fulltext' to appropriate values.
353
-
354
-Removes trailing slashes.
355
-
356
-=item link_bar(@extra_links)
357
-
358
-Returns a little context-sensitive navigation bar.
359
-
360
-=item year($year)
361
-
362
-List out the updates for a year.
363
-
364
-=item month($month)
365
-
366
-Prints the entries in a given month (nnnn/nn).
367
-
368
-=item entry_stamped($entry, $level)
369
-
370
-Wraps entry() + a datestamp in entry_markup().
371
-
372
-=item entry_topic_list($entry)
373
-
374
-Get a list of topics (by tag-* files) for the entry.  This hardcodes part of a
375
-p1k3-specific thing which should be moved into wrt entirely.
376
-
377
-=item entry($entry)
378
-
379
-Returns the contents of a given entry. Calls dir_list and icon_markup.
380
-Recursively calls itself.
381
-
382
-=item get_sub_entries($entry_loc)
383
-
384
-Returns "sub entries" based on the C<subentry_expr> regexp.
385
-
386
-=item list_contents($entry, @entries)
387
-
388
-Returns links (maybe with icons) for a set of sub-entries within an entry.
389
-
390
-=item icon_markup($entry, $alt)
391
-
392
-Check if an icon exists for a given entry if so, return markup to include it.
393
-Icons are PNG or JPEG image files following a specific naming convention:
394
-
395
-  index.icon.[png|jp(e)g] for directories
396
-  [filename].icon.[png|jp(e)g] for flat text files
397
-
398
-Calls image_size, uses filename to determine type.
399
-
400
-=item datestamp($entry)
401
-
402
-Returns a nice html datestamp / breadcrumbs for a given entry.
403
-
404
-=item fragment_slurp($file)
405
-
406
-Read a text fragment, call line_parse() and eval_perl() to take care of
407
-lightweight markup sections and interpret embedded code, and then return it as
408
-a string. Takes one parameter, the name of the file.
409
-
410
-=item root_locations($file)
411
-
412
-Given a file/entry, return the appropriate concatenations with entry_dir and
413
-url_root.
414
-
415
-=item feed_print(@entries)
416
-
417
-Return an Atom feed for the given list of entries.
418
-
419
-Requires XML::Atom::SimpleFeed.
420
-
421
-XML::Atom::SimpleFeed will give bogus results with input that's just a string
422
-of octets (I think) if it contains characters outside of US-ASCII.  In order to
423
-spit out clean UTF-8 output, we need to use Encode::decode() to flag entry
424
-content as UTF-8 / represent it internally as a string of characters.  There's
425
-a whole lot I don't really understand about how this is handled in Perl, and it
426
-may be a locus of bugs elsewhere in wrt, but for now I'm just dealing with it
427
-here.
428
-
429
-Some references on that:
430
-
431
-=over
432
-
433
-=item * L<https://github.com/ap/XML-Atom-SimpleFeed/issues/2>
434
-
435
-=item * L<https://rt.cpan.org/Public/Bug/Display.html?id=19722>
436
-
437
-=item * L<https://cpanratings.perl.org/dist/XML-Atom-SimpleFeed>
438
-
439
-=item * L<perlunitut>
440
-
441
-=back
442
-
443
-=back
444
-
445
-=head1 SEE ALSO
446
-
447
-walawiki.org, Blosxom, rassmalog, Text::Textile, XML::Atom::SimpleFeed,
448
-Image::Size, CGI::Fast, and about a gazillion static site generators.
449
-
450
-=head1 AUTHOR
451
-
452
-Copyright 2001-2017 Brennen Bearnes
453
-
454
-=head1 LICENSE
455
-
456
-    wrt is free software; you can redistribute it and/or modify
457
-    it under the terms of the GNU General Public License as published by
458
-    the Free Software Foundation; either version 2 of the License, or
459
-    (at your option) any later version.
460
-
461
-    This program is distributed in the hope that it will be useful,
462
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
463
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
464
-    GNU General Public License for more details.
465
-
466
-    You should have received a copy of the GNU General Public License
467
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
468
-

+ 3
- 5
lib/App/WRT.pm View File

@@ -1,6 +1,6 @@
1 1
 package App::WRT;
2 2
 
3
-use version; our $VERSION = version->declare("v6.2.3");
3
+use version; our $VERSION = version->declare("v6.2.4");
4 4
 
5 5
 use strict;
6 6
 use warnings;
@@ -31,8 +31,6 @@ use App::WRT::Util   qw(dir_list get_date file_get_contents);
31 31
 
32 32
 App::WRT - WRiting Tool, a static site/blog generator and related utilities
33 33
 
34
-=for HTML <a href="https://travis-ci.org/brennen/wrt"><img src="https://travis-ci.org/brennen/wrt.svg?branch=master"></a>
35
-
36 34
 =head1 SYNOPSIS
37 35
 
38 36
 Using the commandline tools:
@@ -1061,11 +1059,11 @@ sub feed_print {
1061 1059
 =head1 SEE ALSO
1062 1060
 
1063 1061
 walawiki.org, Blosxom, rassmalog, Text::Textile, XML::Atom::SimpleFeed,
1064
-Image::Size, CGI::Fast, and about a gazillion static site generators.
1062
+Image::Size, and about a gazillion static site generators.
1065 1063
 
1066 1064
 =head1 AUTHOR
1067 1065
 
1068
-Copyright 2001-2017 Brennen Bearnes
1066
+Copyright 2001-2019 Brennen Bearnes
1069 1067
 
1070 1068
 =head1 LICENSE
1071 1069
 

Loading…
Cancel
Save