A Short Stay is a game I have written in a Markdown file, doing my best to respect correct usage of HTML tags. I write in Markdown because it is straightforward and flexible, I do not always give a shit about correct usage of HTML, especially when I am writing documents for my own consumption, such as class notes, or project outlines. Most of the Markdown I write is a final output, but a strong value of Markdown is that it is both human readable, and straightforward to parse programatically, which then enables it to be converted and acted upon. The direct purpose of Markdown is to be converted into HTML. Every Markdown thing encodes an HTML thing onto the text, which can be decoded and recoded by software into HTML, which can be rendered by HTML, and styled by CSS.

PDFs are great, love PDFs, and I use several tool chains to produce PDFs, mainly Affinity Publisher, but also sometimes Prince (XML). Affinity is a WYSIWYG layout program, it’s good, I recommend it. Prince is a commandline program that takes various documents including HTML and renders them to PDF.

The core issue at hand, btw there’s an issue here, is that doing extensive layout with Prince means writing a lot of CSS, and, because PDFs are a paged document format (no it doesn’t stand for that), that CSS has to utilize a lot of stuff that doesn’t exist on websites, because websites are not paged like books are. It’s also slow because you have to make code changes and Activate Prince to see what that has done. Meanwhile Affinity Publisher is incapable of producing accessible PDFs.

Accessibility

There’s a few different concepts to approach accessibility in PDFs. Number 1, the PDF must be tagged, tagging is the basis of all further accessibility. As of my last delve into this, several weeks ago, it was still true that Affinity Publisher cannot produce tagged PDFs. Everything else is kinda moot after that, but the goal is to produce a PDF that is compliant with PDF/UA, a specific standard that requires the whole big checklist of things that make a PDF accessible.

Prince can render with the PDF/UA standard, you still have to make a document that is compliant, but it is able to check all the procedural boxes, and there are tools to confirm that the document as a whole is compliant. This is not merely a technological limitation, you must also do the job well. It is however a tech blocked problem. If your tools cannot do PDF/UA, you’re fucked.

I am not sufficiently good at CSS to make a document I am satisfied with by hand. I do not have the energy or time to make a document by hand at all. I just can’t. I did a lot of manual tweaking on the HTML, I did a lot of manual checking on the HTML. I’m not happy that it is maximally accessible, because I feel like accessibility is communicated very poorly by these tools and technologies. I do not feel that I know where the goalposts are, but I did put two whole days in and I got the tools to say I was doing a good job.

Here’s the thing though: Well intentioned HTML has many legs up on PDFs from the jump. That whole Tagged PDF thing, well, HTML is tags. You can’t HTML without it being tagged; you can use HTML tags inappropriately — again, it’s on you to do a good job — but HTML has a relatively low bar for very high accessibility, and I tried to push a little past that.

Now, I used a lot of DL, DT, DD, and I’m getting mixed messages about how appropriate my use has been. I think it’s Not Wrong, but I couldn’t find a more appropriate HTML structure short of a table, and I didn’t want this structured as a table. I could have made it look how I wanted with a lot of CSS buffoonery, but I’m not up to that currently

<dl>
  <dt>Ace</dt>
  <dd>A momento of good times before these, of good times after hard, that stands to remind you to hope.</dd>
</dl>

Ace

A momento of good times before these, of good times after hard, that stands to remind you to hope.

Files Not Found

I have not provided a “plaintext” download. This is another conflicted choice. My understanding is that screen readers broadly understand Markdown, and the purpose of a plaintext file is to be free of the failures in effort and consideration that compound in more complex formats like PDF. HTML is the gold standard for accessibility, if you use a screen reader, please tell me how well my file works. Especially if it works badly! If it does, I’m deeply sorry, but I hope it works adequately. If HTML is the gold standard and mine is brass, then plaintext is tin. I do not grasp how to format a structured document in plaintext, this is why I use Markdown. If you’re comfortable with Markdown, I have included that as well, it is very close to plaintext.

I have not provided a PDF, as described above, and I do not expect to. I don’t think I can produce a PDF/UA file to my own standards without purchasing an Adobe subscription, or manually performing a large amount of CSS. Hopefully someday Affinity Publisher releases support for accessible PDFs, but they haven’t in a long time, and EU law has required accessible PDFs for a while, so I’m not waiting.

Thoughts

Personally I think the attachment to the PDF format is kind of unjustified. It’s an excellent format for documents that will be printed. I don’t think anyone is going to print my games. I made a printable version of Moons Among Us, because I wanted to. I would like to print that. I don’t have a printer and if I did I would not pay for color, so that’s probably not going to happen anytime soon. As no version of A Short Stay “is” laid out, there could be no “printable” version, both the markdown and the html can be printed as is.

What does PDF get us? Portability? well every platform can display html files. Accessibility? only if you pay adobe. A grand canvas to create visual art with our game inset? Yea, I mean, HTML can do that too. Secure claim to authorship? No, also I do not care and I’m not convinced that PDFs are providing that security for most people, or that it is a valid concern. Nobody is plagiarizing my work in a way that matters.

On Errors

In writing this devlog I discovered that I made a minuscule mistake that doesn’t matter, and have uploaded a new version of both files where this mistake is corrected