1. Introduction

I need better generated HTML in txt2tags. Ran output through tidy and it's now standards-compliant.

NOTE: This index.htm is broken -- my CSS doesn't put the TOC at the right like it should.

* <html> needs "lang" attribute.
* Need better contrast for links -- 3:1 contrast ratio.
* No landmark elements.

Page top should be:

<!DOCTYPE html>
<html lang="en">

I'd also like some better META tags in the header. Maybe those could be generated by options like --author, --desc, etc?

<meta name="Author" content="$(AUTHOR)s" />
<meta name="Description" content="$(DESC)s" />
<meta name="Generator" content="txt2tags" />
<meta name="Keywords" content="$(KEYWORDS)s" />
<meta name="Last-Modified" content="$(MODIFIED)s" />
<meta name="UUID" content="$(UUID)s" />

2. Files

arch.tgz: all the files below.
Makefile: builds the HTML files and makes the tarball for upload to my website.
article-got.htm: What I get when running txt2tags3.
article-v3.1.htm: What I get when running v3.1.
article-want.htm: What I mostly want, as far as positioning and format is concerned.
article.t2t: Used to generate the article*.htm pages. It's part of another project, so the links mostly won't work.
diffs: Output from diff -Naur article-got.htm article-want.htm
dot-txt2tagsrc: My .txt2tagsrc file.
index.htm: Generated from index.t2t
index.t2t: This file.
landmark-elements: Short summary of landmark elements for accessibility.
link-contrast.htm: Shows desired contrast for link accessibility.
txt2tags-my-try: My horrible attempt at changing v3.1 to allow for HTML5 output.
txt2tags.css: The stylesheet I prefer for my articles.
txt2tags3: Your Python code.

3. Landmarks

HTML5 elements such as "main", "nav", and "aside" act as landmarks, or special regions on the page to which screen readers and other assistive technologies can jump. By using landmark elements, you can dramatically improve the navigation experience on your site for users of assistive technology. Learn more in Deque University's HTML 5 and ARIA Landmarks (https://dequeuniversity.com/rules/axe/4.4/landmark-one-main).

Use the W3C list of landmark elements (https://www.w3.org/WAI/ARIA/apg/example-index/landmarks/HTML5.html) to check that each major section of your page is contained by a landmark element. For example:

<header>
  <p>Put product name and logo here</p>
</header>
<nav>
  <ul>
    <li>Put navigation here</li>
  </ul>
</nav>
<main>
  <p>Put main content here</p>
</main>
<footer>
  <p>Put copyright info, supplemental links, etc. here</p>
</footer>

You can also use tools like Microsoft's Accessibility Insights (https://accessibilityinsights.io/) extension to visualize your page structure and catch sections that aren't contained in landmarks:

3.1. How to use landmarks effectively

Use landmark elements to define major sections of your page instead of relying on generic elements like <div> or <span>.
Use landmarks to convey the structure of your page. For example, the "main" element should include all content directly related to the page's main idea, so there should only be one per page. See MDN's summary of content sectioning elements (https://developer.mozilla.org/docs/Web/HTML/Element#content_sectioning) to learn how to use each landmark.
Use landmarks judiciously. Having too many landmarks can actually make navigation /more/ difficult for assistive technology users because it prevents them from easily skipping to a desired piece of content.

4. Contrast examples

The following 26 web-safe colors pass at 3:1 vs black and 5:1 vs. white:

#CC0000     << GOOD red     Contrast Ratio = 5.89:1
#CC0033
#CC0066
#CC0099
#9900CC
#6600FF
#9900FF
#CC3300
#CC3333
#993366
#993399
#9933CC
#3333FF
#6633FF
#336600
#666600
#336633
#666633
#006666
#336666
#666666
#006699
#336699
#666699
#0066CC     << GOOD blue        Contrast Ratio = 5.57:1
#3366CC

5. Current status

I'm getting closer, but I can't get the <nav> and <main> headers to show up. I found a way to set the minimum font-size in CSS, so it looks the same on my workstation and my website:

body {
  font-size:  calc(4pt + 1vw);     /* minimum font size */
}

6. Feedback

Feel free to send comments.

Generated from index.t2t by txt2tags
$Revision: 1.3 $
$UUID: 4da42323-f65b-3349-a8bd-ea6da7ac9810 $

Making txt2tags HTML standards-compliant

Karl Vogel