3.2 Texiblog ============ Texinfo is the official documentation format of the GNU project. It is used by many non-GNU projects as well. -- _GNU Texinfo manual_ ‘texiblog’ is my home-grown solution for building a static site, and is what is behind my personal website. It uses ‘texi2any’ to create the HTML from Texinfo files, adds some styling options, creates updated menus from the posts (to provide an easy way to check recent articles), and uses ‘m4’ throughout as a pre-processor and as a way to create the Atom and RSS XML files, as well as other niceties. The code is available at the ‘texiblog’ Notabug repository (1). In the next sections I will go a bit more in-depth about it, but the short version is that _using Texinfo produces a content-focused website, with minimal distractions, easily viewable through any browser, and makes it natural to maintain a structure that is predictable, easy to use, and maps well into other formats, such as a PDF, or a standalone ‘.info’ file_. There's some traction on 'Brutalism in web design', and if taken in one of its forms - the one that focus on showing content with minimal distractions, as described in David Copeland's 'Guidelines for Brutalist Web Design' (2), a good description of this approach - this approach closely follows it, but not because of an explicit desire to do so, but because those are the results of using the Texinfo toolchain (*Note Texinfo for the web::). 3.2.1 Why Texinfo for a personal site. -------------------------------------- There are a lot of 'markdown' flavours out there, and I have previously (and currently) used AsciiDoc and Markdown. I am far from the first one using this approach: using TeX for websites was reasonably common, and one will find examples as this 'Worse is Better' copy on Jamie Zawinki's site (3), which were initially created with ‘latex2html’. Texinfo is simpler than LaTeX, and its usage as the documentation format for the GNU project makes it come with some really good features for a static web site, especially when the goal is to _keep focus on the content_. Stargrave's example ................... When I started to think about this idea I went searching for existing examples, and I found Sergey Matveev's homepage (4), which is not only created using Texinfo (‘texi2html’, most likely), he does an in-depth comparison of formats and why he chose Texinfo. The entire site had exactly the 'feel' I was after: good indexing, simple navigation that is easy to use, and a degree of familiarity that comes from reading a lot of GNU documentation (in ‘info’ or converted to HTML), which I find 'clean'. Technomancy and m4 .................. Texinfo already comes with ‘texi2any’, the current replacement of ‘texi2HTML’, so much of the heavy-lifting is already done for us. I needed some extra features, and for that Phil Hagelberg - aka ‘technomancy’ (5) provided additional inspiration: his entire website is made through a Makefile and ‘m4’ - which some of you will remember as the language used for the configuration of Sendmail, at least those that didn't directly edited the generated file - which it's awesome in itself, but also made me investigate how could I leverage parts of it for my solution. Chrisman Brown does a good description of the ‘m4’ approach (6) used there, and it made be learn a bit more about ‘m4’: I initially had a bunch of scripts that worked on templates, and in the end I was left with only the Makefile, with ‘m4’ doing the work. 3.2.2 What does it do --------------------- Obviously, it creates web output from Texinfo files, using ‘texi2any’, but there's more going on. “*Makefile*” The Makefile defines all targets and uses ‘m4’, ‘awk’, and a couple of other standard tools to create the site. “*M4 configuration files*” The main configuration is done with ‘m4’, which is used to generate any Texinfo file that needs processing, as well as defining the main configuration variables (e.g., website title). $ ls -1 src/*.m4 src/atom.m4 src/config.m4 src/config.texi.m4 src/feed.m4 src/posts.m4 src/rss.m4 “*CSS*” There's a case for not adding anything to the output: the result is indeed ready to use. I have opted for some tweaks, especially in terms of maximum width to keep the text more readable, as well as some slight changes to how the page works on different screen sizes. “*Atom and RSS feeds*” It's also ‘m4’ that creates Atom XML and RSS XML files, which are then included in the generated files. “*Post descriptions and dates*” ‘texi2any’ has a nifty feature that does without the need to manually create Texinfo menus by hand (7): when exporting to HTML, it creates a table of contents for any sections 'under' the Top node. This would work great, except for two things: using a menu allows me to add a description to the entry, which in the case of posts (i.e. the 'blog' aspect of this) can be used to indicate the date. Additionally, it's useful to have control on what gets shown in some sections, especially at the very start of the page where I want to give quick links to the most important sections. The downside of this is that automatically generated menus do not have a description, so ‘m4’ (again) goes through all files under ‘src/posts/’ and creates a menu using the ‘@date’ field. “*Texinfo macros*” Some macros are added to either simplify some things, or make other possible: the ‘@date’ macro is important to make the previously described menu automation work, while others such as ‘@imagec’ simplify adding a float, with an image and a caption. “*Post-processing*” This is a bit open-ended, but currently includes changing the navigation bar to always include a link to the home page (that's the ‘[Top]’ link that appears last, and which isn't a part of the default navbar). More than 90% of the approach is simply based on writing Texinfo files. ---------- Footnotes ---------- (1) ‘texiblog’ Notabug repository (https://notabug.org/fsm/texiblog) (2) David Copeland's 'Guidelines for Brutalist Web Design' (https://brutalist-web.design/) (3) as this 'Worse is Better' copy on Jamie Zawinki's site (https://www.jwz.org/doc/worse-is-better.html) (4) Sergey Matveev's homepage (http://www.stargrave.org/InfoRules.html) (5) Phil Hagelberg - aka ‘technomancy’ (https://technomancy.us/colophon) (6) Chrisman Brown does a good description of the ‘m4’ approach (https://chrisman.github.io/9.html) (7) Texinfo menus by hand (https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Menus.html)