Browse Source

add wrt-ls; minor tidying of documentation

wrt-ls is a provisional interface to the tools in WRT::EntryStore.  It
should do more, but work is needed that I'm not going to put in before
releasing v5.0.0.

This seems like a good point to call things stable for this major release.
I have a bunch of ideas that I'd like to implement for a v6, which might
well break the API and underlying data structures.

This is all pretty academic since no one else actually uses this thing.
Brennen Bearnes 6 days ago
parent
commit
80accedb33
9 changed files with 90 additions and 64 deletions
  1. 24
    16
      README.pod
  2. 1
    1
      bin/wrt
  3. 1
    1
      bin/wrt-config
  4. 1
    1
      bin/wrt-display
  5. 1
    1
      bin/wrt-init
  6. 30
    20
      bin/wrt-ls
  7. 2
    2
      bin/wrt-render-all
  8. 24
    16
      lib/App/WRT.pm
  9. 6
    6
      lib/App/WRT/Markup.pm

+ 24
- 16
README.pod View File

@@ -13,8 +13,10 @@ Using the commandline tools:
13 13
     $ mkdir project
14 14
     $ cd project
15 15
     $ wrt init         # set up some defaults
16
-    $ wrt display new  # print html for new posts to stdout
17
-    $ wrt render-all   # publish html to project/public/
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/
18 20
 
19 21
 Using App::WRT in library form:
20 22
 
@@ -31,9 +33,16 @@ Using App::WRT in library form:
31 33
 =head1 INSTALLING
32 34
 
33 35
 It's possible but not likely this would run on a Perl as old as 5.10.0.  In
34
-practice, I know that it works under 5.20.2.  It should be fine on any
35
-reasonably modern Linux distribution, and may also be fine on MacOS or a BSD of
36
-your choosing.
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.)
37 46
 
38 47
 To install the latest development version from the main repo:
39 48
 
@@ -56,11 +65,11 @@ You will likely need to use C<sudo> or C<su> to get a systemwide install.
56 65
 
57 66
 =head1 DESCRIPTION
58 67
 
59
-This started life as C<display.pl>, a simple script to concatenate fragments of
60
-handwritten HTML by date.  It has since accumulated several of the usual weblog
61
-features (lightweight markup, feed generation, embedded Perl, poetry tools,
62
-image galleries, and ill-advised dependencies), but the basic idea hasn't
63
-changed that much.
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.
64 73
 
65 74
 The C<wrt> utility now generates static HTML files, instead of expecting to
66 75
 run as a CGI script.  This is a better idea, for the most part.
@@ -145,17 +154,16 @@ on it.
145 154
 Embedded code and variables are intended only for use in the F<template> file,
146 155
 where it's handy to drop in titles or conditionalize aspects of a layout. You
147 156
 want to be careful with this sort of thing - it's useful in small doses, but
148
-it's also a maintainability nightmare waiting to happen.  (WordPress, I am
149
-looking at you.)
157
+it's also a maintainability nightmare waiting to happen.
150 158
 
151 159
 B<Includes> - replaced by the contents of the enclosed file path, from the
152 160
 root of the current wrt project:
153 161
 
154 162
     <include>path/to/file</include>
155 163
 
156
-This is a bit constraining, since it doesn't allow for files outside of the
157
-current project, but is useful for including HTML generated by an external
158
-script in a page.
164
+This is a bit constraining, since it doesn't currently allow for files outside
165
+of the current project, but is useful for including HTML generated by an
166
+external script in a page.
159 167
 
160 168
 B<Several forms of lightweight markup>:
161 169
 
@@ -167,7 +175,7 @@ B<Several forms of lightweight markup>:
167 175
 
168 176
      <freeverse>An easy way to
169 177
      get properly broken lines
170
-     plus -- en and em dashes ---
178
+     plus -- em dashes --
171 179
      for poetry and such.</freeverse>
172 180
 
173 181
 B<And a couple of shortcuts>:

+ 1
- 1
bin/wrt View File

@@ -37,7 +37,7 @@ L<https://code.p1k3.com/gitea/brennen/wrt>.
37 37
 
38 38
 =head1 AUTHOR
39 39
 
40
-Brennen Bearnes
40
+Brennen Bearnes <code@p1k3.com>
41 41
 
42 42
 =cut
43 43
 

+ 1
- 1
bin/wrt-config View File

@@ -34,7 +34,7 @@ archive.
34 34
 
35 35
 =head1 AUTHOR
36 36
 
37
-Brennen Bearnes
37
+Brennen Bearnes <code@p1k3.com>
38 38
 
39 39
 =cut
40 40
 

+ 1
- 1
bin/wrt-display View File

@@ -57,7 +57,7 @@ L<https://code.p1k3.com/gitea/brennen/wrt>.
57 57
 
58 58
 =head1 AUTHOR
59 59
 
60
-Brennen Bearnes
60
+Brennen Bearnes <code@p1k3.com>
61 61
 
62 62
 =cut
63 63
 

+ 1
- 1
bin/wrt-init View File

@@ -34,7 +34,7 @@ L<https://code.p1k3.com/gitea/brennen/wrt>.
34 34
 
35 35
 =head1 AUTHOR
36 36
 
37
-Brennen Bearnes
37
+Brennen Bearnes <code@p1k3.com>
38 38
 
39 39
 =cut
40 40
 

+ 30
- 20
bin/wrt-ls View File

@@ -1,5 +1,22 @@
1 1
 #!/usr/bin/env perl
2 2
 
3
+# TODO:
4
+#
5
+# Ideally, this would be able to handle the following gracefully:
6
+#
7
+#   wrt ls 2016     # all entries for 2016
8
+#   wrt ls 2016/4   # all entries for April 2016
9
+#   wrt ls 2016/4/1 # everything for April 1, 2016
10
+#
11
+# ...but I think doing that right requires a much cleaner separation of how
12
+# entries are _structured_ from how they're _displayed_, probably by moving
13
+# more operations into WRT::EntryStore.
14
+#
15
+# It makes some sense that wrt-ls would just expose the interface of
16
+# EntryStore in a relatively safe way, including the operations that find
17
+# things by depth, locate the next/previous entry, etc.  All of these could
18
+# be useful in scripting and publishing pipelines.
19
+
3 20
 =pod
4 21
 
5 22
 =head1 NAME
@@ -9,9 +26,6 @@ wrt-ls - list
9 26
 =head1 USAGE
10 27
 
11 28
     wrt ls          # all entries
12
-    wrt ls 2016     # all entries for 2016
13
-    wrt ls 2016/4   # all entries for April 2016
14
-    wrt ls 2016/4/1 # everything for April 1, 2016
15 29
     wrt ls --days   # entries for individual days
16 30
     wrt ls --months # entries for individual months 
17 31
     wrt ls --years  # entries for years
@@ -26,6 +40,8 @@ wrt-ls - list
26 40
 
27 41
 Lists entries in the current wrt archive.
28 42
 
43
+This interface is experimental and subject to revision in upcoming releases.
44
+
29 45
 Detailed documentation can be found in the L<App::WRT> man page or at
30 46
 L<https://code.p1k3.com/gitea/brennen/wrt>.
31 47
 
@@ -87,27 +103,21 @@ unless (-e $config_file) {
87 103
 
88 104
 my $w = App::WRT::new_from_file($config_file);
89 105
 
90
-# Did we get any patterns to match against?
91
-if (@ARGV) {
92
-  
93
-}
94
-
106
+# Define the function that'll return the base list of entries to match
107
+# against:
108
+my $base_list;
95 109
 if ($list_days) {
96
-  foreach my $entry ($w->{entries}->all_days()) {
97
-    say $entry;
98
-  }
110
+  $base_list = sub { $w->{entries}->all_days(); };
99 111
 } elsif ($list_months) {
100
-  foreach my $entry ($w->{entries}->all_months()) {
101
-    say $entry;
102
-  }
112
+  $base_list = sub { $w->{entries}->all_months(); };
103 113
 } elsif ($list_years) {
104
-  foreach my $entry ($w->{entries}->all_years()) {
105
-    say $entry;
106
-  }
114
+  $base_list = sub { $w->{entries}->all_years(); };
107 115
 } elsif ($list_all) {
108
-  foreach my $entry ($w->{entries}->all()) {
109
-    say $entry;
110
-  }
116
+  $base_list = sub { $w->{entries}->all(); };
117
+}
118
+
119
+foreach my $entry ($base_list->()) {
120
+  say $entry;
111 121
 }
112 122
 
113 123
 exit(0);

+ 2
- 2
bin/wrt-render-all View File

@@ -4,7 +4,7 @@
4 4
 
5 5
 =head1 NAME
6 6
 
7
-wrt-render-all - utility for rendering static HTML files from entries
7
+wrt-render-all - utility for rendering static HTML files from wrt entries
8 8
 
9 9
 =head1 USAGE
10 10
 
@@ -30,7 +30,7 @@ L<https://code.p1k3.com/gitea/brennen/wrt>.
30 30
 
31 31
 =head1 AUTHOR
32 32
 
33
-Brennen Bearnes
33
+Brennen Bearnes <code@p1k3.com>
34 34
 
35 35
 =cut
36 36
 

+ 24
- 16
lib/App/WRT.pm View File

@@ -42,8 +42,10 @@ Using the commandline tools:
42 42
     $ mkdir project
43 43
     $ cd project
44 44
     $ wrt init         # set up some defaults
45
-    $ wrt display new  # print html for new posts to stdout
46
-    $ wrt render-all   # publish html to project/public/
45
+    $ wrt config       # dump configuration values
46
+    $ wrt ls           # list entries
47
+    $ wrt display new  # print HTML for new entries to stdout
48
+    $ wrt render-all   # publish HTML to project/public/
47 49
 
48 50
 Using App::WRT in library form:
49 51
 
@@ -60,9 +62,16 @@ Using App::WRT in library form:
60 62
 =head1 INSTALLING
61 63
 
62 64
 It's possible but not likely this would run on a Perl as old as 5.10.0.  In
63
-practice, I know that it works under 5.20.2.  It should be fine on any
64
-reasonably modern Linux distribution, and may also be fine on MacOS or a BSD of
65
-your choosing.
65
+practice, I know that it works under 5.26.2.  It should be fine on any
66
+reasonably modern Linux distribution, and may work on MacOS or a BSD of your
67
+choosing.  It's possible that it would run under the Windows Subsystem for
68
+Linux, but it would definitely fail under vanilla Windows; it currently makes
69
+too many assumptions about things like directory path separators and filesystem
70
+semantics.
71
+
72
+(Although I would like the code to be more robust across platforms, this is not
73
+a problem I feel much urgency about solving at the moment, since I'm pretty
74
+sure I am the only user of this software.  Patches would certainly be welcome.)
66 75
 
67 76
 To install the latest development version from the main repo:
68 77
 
@@ -85,11 +94,11 @@ You will likely need to use C<sudo> or C<su> to get a systemwide install.
85 94
 
86 95
 =head1 DESCRIPTION
87 96
 
88
-This started life as C<display.pl>, a simple script to concatenate fragments of
89
-handwritten HTML by date.  It has since accumulated several of the usual weblog
90
-features (lightweight markup, feed generation, embedded Perl, poetry tools,
91
-image galleries, and ill-advised dependencies), but the basic idea hasn't
92
-changed that much.
97
+This started life somewhere around 2001 as C<display.pl>, a CGI script to
98
+concatenate fragments of handwritten HTML by date.  It has since accumulated
99
+several of the usual weblog features (lightweight markup, feed generation,
100
+embedded Perl, poetry tools, image galleries, and ill-advised dependencies),
101
+but the basic idea hasn't changed that much.
93 102
 
94 103
 The C<wrt> utility now generates static HTML files, instead of expecting to
95 104
 run as a CGI script.  This is a better idea, for the most part.
@@ -174,17 +183,16 @@ on it.
174 183
 Embedded code and variables are intended only for use in the F<template> file,
175 184
 where it's handy to drop in titles or conditionalize aspects of a layout. You
176 185
 want to be careful with this sort of thing - it's useful in small doses, but
177
-it's also a maintainability nightmare waiting to happen.  (WordPress, I am
178
-looking at you.)
186
+it's also a maintainability nightmare waiting to happen.
179 187
 
180 188
 B<Includes> - replaced by the contents of the enclosed file path, from the
181 189
 root of the current wrt project:
182 190
 
183 191
     <include>path/to/file</include>
184 192
 
185
-This is a bit constraining, since it doesn't allow for files outside of the
186
-current project, but is useful for including HTML generated by an external
187
-script in a page.
193
+This is a bit constraining, since it doesn't currently allow for files outside
194
+of the current project, but is useful for including HTML generated by an
195
+external script in a page.
188 196
 
189 197
 B<Several forms of lightweight markup>:
190 198
 
@@ -196,7 +204,7 @@ B<Several forms of lightweight markup>:
196 204
 
197 205
      <freeverse>An easy way to
198 206
      get properly broken lines
199
-     plus -- en and em dashes ---
207
+     plus -- em dashes --
200 208
      for poetry and such.</freeverse>
201 209
 
202 210
 B<And a couple of shortcuts>:

+ 6
- 6
lib/App/WRT/Markup.pm View File

@@ -261,15 +261,15 @@ Inline replace <textile> markup in a string.
261 261
 =cut
262 262
 
263 263
 # This is exactly the kind of code that, even though it isn't doing anything
264
-# especially insane, looks ghastly to people who don't read Perl, so I'll try
265
-# to explain a bit.
264
+# especially over the top, looks ghastly to people who don't read Perl, so I'll
265
+# try to explain a bit.
266 266
 
267 267
 sub textile_process {
268 268
 
269 269
   # First, there's a state variable here which can retain the Text::Textile
270
-  # object between invocations, saving us a bit of time on subsequent calls.
271
-  # This should be equivalent to creating a closure around the function and
272
-  # keeping a $textile variable there.
270
+  # object between invocations of the function, saving us a bit of time on
271
+  # subsequent calls.  This should be equivalent to creating a closure around
272
+  # the function and keeping a $textile variable there.
273 273
   state $textile;
274 274
 
275 275
   # Second, instead of unrolling the arguments to the function, we just act
@@ -279,7 +279,7 @@ sub textile_process {
279 279
 
280 280
   $_[0] =~ s{
281 281
 
282
-    # find tags...
282
+    # Find tags...
283 283
 
284 284
     <textile>  # start tag
285 285
       (.*?)    # anything (non-greedy)

Loading…
Cancel
Save