So what is Restructured Text?

Restructured Text or RST is a way to describe the structure of a document simply that you can learn how to use in a few minutes. Once you have created an RST document you can run converters on it to create web pages, PDFs, EPUBs, and other more complex documents.

The desktop publishing system called LaTex (pronounced "lay-tek") can create beautifully formatted books, but it has a fairly steep learning curve. A good way to flatten that curve is to create your book text in RST, then run a conversion utility to make a TEX file out of it. Once you have that TEX file you can do a little tinkering on it to make a PDF that you can use for a print-on-demand book interior, without having to learn everything about TEX first.

I first learned about RST when I donated books to Project Gutenberg, a site where volunteers create free ebooks from books that have fallen into the public domain. PG requires donations be submitted in two formats:

1. A web page that follows certain rules.

2. A plain text page that follows certain rules.

You need to create both of these. One way you might do that is to create the plain text file first, make a copy of it, then go through the copy and add HTML tags for chapter headings, paragraphs, images, etc. That is what I used to do.

PG plain text files need to have a certain line length, need to represent bolded and italicized text a certain way, need to indicate where an illustration is in the original book text, and need to represent footnotes a certain way. Just creating the plain text file was a lot of work, then you needed to proofread it carefully before making the web page version so you didn't have to make the same corrections in two files.

Some people at PG got the idea that instead of creating two differently formatted files with the same text a volunteer might save a lot of work by making an RST file and using conversion utilities to generate the web page and the plain text file from that. It was a good idea, but it never caught on with PG volunteers. I was one of only a handful of people who tried it, which is unfortunate because the method saves a lot of work.

To give you an idea of just how simple the RST format it, here is a sample document in the format:

========
Book Title
========

Chapter Heading
--------------------

Section Heading
``````````````````

This is a paragraph with some *italicized text* and some **bold text**.

This paragraph has a footnote [#]_.

.. [#] This is the text of that footnote.

There is more you can do with RST, but that will give you an idea of how it works. Headings have a line of characters underneath them the same length as the heading.

The complete documentation for creating an RST file will be found here:

https://docutils.sourceforge.io/docs/...

Details on how to convert your RST file to a finished book interior will follow. Stay tuned.