more ramblings of a retired teacher
commenting (maybe ranting) on education - even my own

May 2024
« Mar    
Filed under: General, F/LOSS
Posted by: Algot @ 12:46 pm

While it may not have any impact on this blog, I’m writing a personal journal. But typically, there is more to it than just the writing. I’m also exploring the AsciiDoc tool as part of my writing environment. AsciiDoc is a text processor which does conversions from plain text files into several other formats such as HTML, ODF, DocBook, among others.

I write the text into my personal choice of text editor, Kate, part of the set of excellent programs from the KDE community. By writing in an unadorned text format, I benefit from long term stability/accessibility of my file. Over the years, I have used all sorts of word processor programs. The big benefit of each is nice layout and WYSIWYG text. The big drawback has been the demise of the word processing programs themselves.

After the program is no longer maintained, its proprietary format fades quickly. It is difficult to import many of those old formats into new programs. Nobody has made an import utility in Microsoft Word for ClarisWorks files, as an example. All the stuff stored on Mac formatted floppies or worse, Apple II floppies is inaccessible, even if I transferred the files from one generation of storage media to the next. Phooey!

AsciiDoc, as its name implies is built around the stable ASCII character set. Pronounced ask-ee, the “American Standard Code for Information Interchange” is still with us, even though it is now only a small part of the international “Universal Transformation Format.” UTF has a way to deal with the many other characters worldwide that are not found in the English alphabet. But the codes of ASCII are the same ones they always were. That means text can easily be imported into any modern word processor.

I wish I had always made it a habit to export a text version of all my school documents instead of just saving in the native format of the word processor I was currently using.

AsciiDoc actually does a sort of double duty. I am learning to add the relatively simple “codes” that look fine as text, but which get processed by the asciidoc program so that I get all the goodies of WYSIWYG in the web pages or ODF (think LibreOffice) files. Little things make the bold and beautiful things happen.

For example if I type *bold* in Kate and then run the saved text file through the conversion to HTML5 with asciidoc, I get bold instead of the word surrounded by the asterisks. Now, I’m sort of used to that convention anyway. I use it on Twitter to tell people I mean bold. I used to do it in my text-only email clients way back. To get italic, I write underscores before and after _italic_. AsciiDoc does the conversion, but the text file remains entirely legible. The extra characters do not get in the way of the text being understood. The extra characters might look a little strange, but the markup is not intrusive markup. To get a new paragraph, just leave a blank line (extra Enter) below the current paragraph before starting to write the next.

From the AsciiDoc User Guide:

AsciiDoc is a plain text human readable/writable document format that
can be translated to DocBook or HTML using the asciidoc(1) command.
You can then either use asciidoc(1) generated HTML directly or run
asciidoc(1) DocBook output through your favorite DocBook toolchain or
use the AsciiDoc a2x(1) toolchain wrapper to produce PDF, EPUB, DVI,
LaTeX, PostScript, man page, HTML and text formats.

The AsciiDoc format is a useful presentation format in its own right:
AsciiDoc markup is simple, intuitive and as such is easily proofed and

AsciiDoc is apparently often part of the preferred documentation tool chain for many Free Software (AKA “open source”) programs.

2 Responses to “Journal”

  1. Ophelia Says:
    Your page’s design looks crappy. You schould change it. Better design means a lot more conversions, faster load and greater confidence of visitors.
  2. Algot Says:
    Thanks, “Ophelia”. While it is clear from the rest of the comment (edited out) that this was like most of the “traffic” the site gets: SPAM. Still, you are right. There is very little control available for the layout of the SiteBlog offered by my hosting company. I much prefer to blog with other tools which have a wider set of options.