My standard technology for writing and "word processing" is the use of a text editor and a lightweight markup language. In this document I'll give some description of what that entails, why I like it, how to do it, and what some of your options are if you decide to pursue that strategy.

What this document is not about -- This document does not discuss data markup languages such as XML, Yaml, and JSON. And, it discusses HTML almost only in reference to the production of HTML from the various lightweight markup languages discussed here.

1   Information sources and references

I'll give some links for information on specific tools further below. But, for your general awareness, you may want to look at a few of the following:

Some implementations of converters for specific lightweight markup languages:

Note the emphasis above on Python implementations, because I'm a Python user. But, you can find other implementations with a few Web searches. Or, see the Wikipedia page on lightweight markup languages for links to home pages for each lightweight markup language.

2   A few benefits and advantages of lightweight markup language

  • If you have a favorite (plain) text editor, you get to use it.
  • Some text editors have special support for specific lightweight markup languages. For example, Vim/Neovim has syntax support for reST, Asciidoc, and Markdown.
  • Conversion to HTML is quick and easy. For some of us, doing that conversion, then viewing the resulting HTML in a Web browser is as good as or better than a WYSIWYG word processor.
  • Your content is transparent; you can see the source.
  • You get all the benefits of working with plain-text files, for example: (1) You can search your source content (e.g. with grep on Linux). (2) You content plays well with a DRCS/SCM/VCS (distributed revision control system/source control management/version control system), e.g. Git (https://git-scm.com/), Mercurial (https://www.mercurial-scm.org/), Breezy/Bazaar (https://www.breezy-vcs.org/), etc.
  • You likely will be able to view and publish your content as a Wiki. Most Wiki implementations store their content in lightweight markup languages. Examples are:
    • Gollum -- stores its content in a Git repository; supports a variety of lightweight markup languages, including Markdown, reStructuredText, and with a little work) Asciidoc, plus more; is written in Ruby -- https://github.com/gollum/gollum
    • Wiki`.js` -- stores its content in a relational database; supports ``Markdown; is written in Node.js/Javascript -- https://js.wiki/
  • You can use a source control management system AKA version control system or revision control system to manage your content files. Because your content is stored in plain text files SCM/VCS/RCS tools work well with it, for example enabling you to use a diff command to look at changes to a specific file across commits/revisions. Git, Mercurial, and Bazaar/Breezy all work well with lightweight markup language content. For more choices, see -- https://en.wikipedia.org/wiki/Comparison_of_version-control_software.

3   A larger, and somewhat historical context

In a sense, formatted text has been with us in simpler and without standardization, for a long time. Stretch things a bit and you can say that humans have been doing it for as long as they've been writing.

It's only recently, since we've had computers that can process text, that we've been able to use that formatting to control the production of viewable and printable output.

And, as an alternative to lightweight markup languages, there are also languages that are more command oriented, for example:

4   How do I ... ?

  • How do I convert my lightweight markup language to HTML?

    The command line tools for the converters/implementations listed above respond to a "--help" command line option. For example:

    $ asciidoc --help
    $ asciidoc --help manpage
    $ asciidoc3 --help
    $ asciidoc3 --help manpage
    $ asciidoctor --help
    $ markdown2 --help
    $ markdown_py --help
      o
      o
      o
    

5   A few questions, and maybe answers, too

  • Are lightweight markup languages for techies only?

    Certainly, you may be able to do more if you are comfortable at the command line. However, for many uses, it's quite simple. For example, here is all it takes to convert a reStructuredText (reST) document and an Asciidoc document to HTML with Docutils and asciidoc3, respectively:

    $ rst2html5.py mydocA.rst mydocA.html
    $ asciidoc3 mydocB.adoc
    

    It can't get much simpler than that.

    Docutils and asciidoc3 are Python tools and can be installed with pip:

    $ pip install docutils
    $ pip install asciidoc3
    
  • Is there "live preview" for my lightweight markup language? There are several kinds of answers for this question:

    1. Take a look at ReText (https://github.com/retext-project/retext).
    2. Use a Wiki with a Web interface for editing and managing content, for example, consider Gollum or Wiki.js.
    3. I use Vim/Neovim for editing documents, usually written in Asciidoc. Using makeprg, enables me to compile/convert a document to HTML with :make. I have a keyboard mapping to :w<cr>:make<cr>, which enables me to save my document and convert it to HTML with a keystroke, and then in my Web browser I refresh and view that newly produced HTML content.
  • What if I want to produce printable/viewable content in some representation other than HTML?

    Several implementations of lightweight markup languages have "back-ends" that produce other kinds of content. For example:

    • Asciidoctor has a plugin that produces PDF from Asciidoc.
    • Docutils has rst2latex.py and rst2xetex.py, which produce LaTeX, which can be converted to PDF, for one.
    • Docutils has rst2odt.py, which produces files understood and read by LibreOffice Writer, which can export other forms of content, specifically PDF and EPUB.
    • Asciidoctor, asciidoc-py, and asciidoc3 all have back-ends for producing Docbook XML, which can, I'm led to believe, be converted to various viewable/printable formats. See: https://docbook.org/.
    • ReText () can produce PDF and ODT/ODF (LibreOffice Writer) files from Markdown and reStructuredText.

Published

Category

documentation

Tags

Contact