| < Pod::Thread | Russ Allbery > Software |
Whenever you set out to do something, something else must be done first.
Murphy's Fourth Corollary
Here you'll find most of the software that I use to generate my web pages. This set of tools came out of my strong dislike of writing HTML, which is a reasonably functional output language but is user-unfriendly, unreadable, and verbose as an entry language, as well as missing some basic capabilities like per-file macros.
All of these programs generate XHTML Strict, except for one non-default mode of faq2html that uses the value attribute of <li> and therefore generates XHTML Transitional. The output in all cases is designed to be used with style sheets to do the formatting.
The core is the program spin, which implements a macro language called thread. All of my regular web pages are written in thread, which looks vaguely like LaTeX but with square brackets around macro arguments and a lot of generosity when it comes to whitespace. Here's a sample of what thread source looks like. spin takes as arguments an input tree and an output tree and regenerates the XHTML files when the thread source has changed. I then use rsync to copy the output tree onto a web server.
spin uses a separate program, spin-rss, to generate RSS files and other dynamic index files based on date-stamped entries.
spin also knows how to invoke other programs to generate XHTML where appropriate. Most of my FAQs are maintained in plain text suitable for posting to Usenet and converted to XHTML by faq2html, run by spin. Software change logs are converted by either cvs2xhtml (which converts CVS log output) or cl2xhtml (which converts GNU-style ChangeLog files). And all of my software documentation is written in POD, the Plain Old Documentation language used primarily by Perl, and converted to thread by Pod::Thread and then to XHTML by spin. The navigation links and signatures at the bottoms of my pages are added automatically by spin.
All of faq2html, cl2xhtml, and cvs2xhtml generate XHTML directly and are usable independent of this system.
All of these programs are designed for my own personal quirks and preferences and therefore may not be particularly useful to anyone other than me, but they're provided here just in case. It's not my intention to try to create a general web markup language, just to write something that works well for my personal needs. That being said, the XHTML generated by cl2xhtml, cvs2xhtml, and (if you write plain text like I do) faq2html is fairly general and can have any style sheet applied to it, so they may be useful. Somewhat to my surprise, various people have found spin and thread useful and interesting and have started using it in places other than my personal web pages.
spin requires Perl 5.005 or later and the Image::Size and Text::Balanced modules.
spin-rss requires Perl 5.6.0 or later and the Date::Parse module, which is part of the TimeDate CPAN distribution.
faq2html only requires Perl 5.003.
cl2xhtml and cvs2xhtml are written in Python as part of my effort to learn the language. They require Python 3 (any version would probably do).
The programs:
| spin 1.80 | 2013-01-04 | Download |
| spin-rss 1.25 | 2012-12-23 | Download |
| faq2html 1.36 | 2021-03-28 | Download |
| cl2xhtml 1.12 | 2021-03-28 | Download |
| cvs2xhtml 1.15 | 2021-03-28 | Download |
Copyright 1999-2011, 2013, 2021 Russ Allbery <eagle@eyrie.org>
spin, spin-rss, and faq2html are distributed under the following license:
These programs are free software; you may redistribute them and/or modify them under the same terms as Perl itself. This means that you may choose between the two licenses that Perl is released under: the GNU GPL and the Artistic License. Please see your Perl distribution for the details and copies of the licenses.
cl2xhtml and cvs2xhtml are distributed under the following license:
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
| < Pod::Thread | Russ Allbery > Software |