3.2 Texiblog

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)