Day 23 – A Raku Advent Helper

Introduction

I have been writing Raku Advent articles annually since 2016, and it’s always been a struggle for me to get a reliable transformation of my source file into the Raku Advent WordPress (WP) website without something getting changed by WP. Then, the menus are terrible and editing can be troublesome. In this article I hope to show how the situation can be improved.

Background

The great name change to Raku this year unfortunately happened late in the year and there was not a lot of time to get a new Raku Advent website ready. Consequently, theme selection and tweaking, confusion over the actual Raku Advent website link, and unfortunate article cancellations were wrinkles in the normally smoother process. However, we plan to improve the website before the 2020 Advent season, and also get commitments earlier with concrete drafts available sooner. In the meantime, in this hastily prepared stand-in article, I will go into a bit of detail on some help we hope to offer.

Article creation

Since my first experience with WordPress, I have found these things that make it awkward for me to use WP:

• Small editing window
• Noticeable lag time while editing increases fumble-finger errors
• Enter the desired schedule time in the website time zone (TZ) but see it displayed in your local TZ (with little or no hint as to what you are seeing) [See Note 1]
• Confusing editing contexts and widget placements

I’m sure most of my problems with WP are self-induced, but I do prefer a more TeX-like document production work flow.

Prior years

In past years I’ve created the articles in Gihub-flavored markdown, manually (with the assistance of my Emacs editor) converted each paragraph to single, long lines, and then posted it in a Github gist. After that, I used the tool p6advent-md2html.p6, developed by @zoffix [Note 2] and modified by @SimonProctor, to extract the html from Github’s representation of the markdown which results in a nice highlighting of code blocks. Finally, that html is copied and pasted into WP and a publishing schedule set up. That original process is outlined here:

1. Write the post in Github-favored Markdown text
2. Collapse each paragraph to one long line
3. Paste the source into a Github gist
4. Use the existing Advent tool to extract the resulting html representation to one’s local computer
5. Copy the html and paste it into the blank, html view of the selected WP editor
6. View the finished product and check for errors

If errors are found:

7. Correct the errors in the WP editor

OR

7. Correct the errors in the source
8. Repeat steps 2 through 6 again

That process is not so bad the first time through it, but when, inevitably, errors are found, one has the choice of either manually editing it on WP or modifying the source and going through the entire process again! Neither choice is very good.

2019’s Advent goal: reduce WP pain

I decided this year to help my article-creation situation so I created a Raku tool to eliminate some of the problems. It’s available to the public as of today:

$ zef install RakuAdvent::WordPress

That module provides the tool make-wp-input. So my new steps as of this year:

1. Write the post in raw html
2. Run my new Advent tool (make-wp-input) to format the source into WP-acceptable html
3. Copy the html and paste it into the blank, html view of the selected WP editor
4. View the finished product and check and correct for errors

If errors are found:

5. Correct the errors in the WP editor

OR, preferably,

5. Correct the errors in the source
6. Repeat steps 2 through 4 again

Thus, in my new process, I’ve eliminated a couple of steps, but I still have to copy/paste my clean WP source into the WordPress editor—but that’s because I have not taken advantage of the available APIs from WordPress and Github to do the drudge work.

However, in spite of other limitations, the new tool has been a huge help in easing the use of live code examples in an article. In my sandbox where I write my article, I create the code samples in their own files and then add the

<!-- insert file-name lang -->

lines as needed in the location needed. That way, I can edit the live code and test it to make sure it works, but don’t have to change the source using that code.

Tips for Raku authors

Here are some ideas I’ve found helpful while developing articles for the Raku Advent:

• See help for the WP scheduling calendar in this video
• Take advantage of your default personal WP website to experiment
• View the finished product as printed PDF, and check and correct for errors (this has been a very good way for me to look over my article at leisure while sipping an egg nog with my BF “by the fire.” 😊; see Ref. 1 for an excellent html-to-pdf converter)

Wish lists

Here are some things I hope to do with make-wp-input in the New Year:

1. Convert html source to Github-flavored markdown
2. Handle html tables
3. Allow paragraphs in the source html to be recognized by either blank lines above and below the text or a line with a closing tag on the line before the text or an opening tag on the line following the text
4. Use Github’s APIs [Ref. 2] to manipulate markdown source to a Github gist and get html results back from it
5. Use WordPress’s APIs [Ref. 3] to manipulate one’s article on WordPress (including setting or updating the publication schedule)

And here are some things I hope the community can do (or at least agree upon) for the Raku Advent website:

1. Improve the theme and code styling.
2. Use the old Perl 6 Advent theme?
3. Sign up for article slots earlier in the year, and start the article (at least in skeleton form) as a scheduled one on the Raku Advent website.

Summary

This year has seen a lot of changes in the Raku community, especially with the name change, and not all are done yet. One area that still needs work is improving the new Raku Advent website. We also hope to make it easier to create and post Raku Advent articles as well as get more participation. Note the 2020 schedule is open now, so you can get your slot early and avoid last minute shopping, er, Raku Adventing!

I ❤️ Raku! 😊

Merry Christmas and a Happy, Blessed New Year to all!

---

APPENDIX

---

Notes

1. I have filed an issue with WordPress to help with time zone identification in the scheduling calendar.
2. Names preceded by @ are IRC or Github aliases.

References

1. wkhtmltopdf (available as a Debian package)
2. Github API
3. WordPress API

Raku modules used

• RakuAdvent::WordPress (v.0.0.2)