Personal Education
One of the pieces of the journal mentioned in the last post is conversion. I suppose for its intended documentation purpose, the AsciiDoc setup is good. I have not explored all the options for the backend. Therefore, the HTML files I get when I do that conversion have a lot of extra “stuff” like an embedded stylesheet and some scripting for generating tables of contents. The conversion to an open document format isn’t smooth, either
I have decided to try looking at using the less complex Markdown syntax and Pandoc along with Kate to do the journal. Pandoc offers a cleaner conversion to html and odt. There is an issue with how small images get inserted. They fill the page width by default. Oops. They can be resized in LibreOffice, but it will be nicer if I can find a way to get the images plunked in place at their correct size (unless the image is huge and needs to fit the page width).
More to come, I’m sure.
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 theasciidoc(1)command.
You can then either useasciidoc(1)generated HTML directly or run
asciidoc(1)DocBook output through your favorite DocBook toolchain or
use the AsciiDoca2x(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
edited.
AsciiDoc is apparently often part of the preferred documentation tool chain for many Free Software (AKA “open source”) programs.