Categories
Tutorials & Tips

Plain text markup languages

Instead of relying in complicated bloated office programs or embedding messy WYSIWYG interfaces in web applications, a quick way to format plain text is to use a markup language. Just like HTML that has tags to structure a document and render into special formatting, plain text can also be “pretty” by using a standard markup language. It is easier to type as they normally don’t interfere much in the visual aspect of the text. That means that even if you don’t have support for the markup language, you can read the text without problems.

On code documentation files, plain text markup languages are preferred over languages like HTML or LaTeX to waste little time on editing without loosing good presentation.

Some of these languages are:

Markdown

It was created as a plain text to HTML markup language made to simplify writing formatted text that will generally end translated to HTML tags. The syntax is very simple and supported on many text editors and web platforms.

Basic markup guide

# Heading 1
## Heading 2
*Bold*
– List item 1
– List item 2
+ sublist item
[text](Link)

Cheatsheet

You can find a markup cheatsheet here

You can read more on the markdown project website.

Asciidoc

As the website defines it, it is more than just a markup language. It is a text based document generation tool. You can create beautiful documentation with it by exporting to formats like HTML, PDF or LaTeX. Besides the usual markup of plain text, you can also use variables with a certain value to reuse across your document, saving you from typing repeated text or update a value in several places with one change.

Basic markup guide

== Heading 1
=== Heading 2
\*Bold\*
* List item 1
* List item 2
** sublist item
link_url[Link_text]

Cheatsheet

There’s an asciidoc cheatsheet here

You can read more at the asciidoc website.

Org

Org was born in the Emacs org-mode users world. I think besides Emacs there are no other places where org syntax is being used. Org lets you do many things in plain text, like organizing your to-do lists, your agenda, plan your projects, add source code blocks and execute the code right in your document among many other things. You can easily export to HTML, LaTeX, PDF among other formats. Some parts of the syntax can be complicated but since it is intended to be used within Emacs, it’s easy to handle with simple keyboard shortcuts.

Basic markup

* Heading 1
** Heading 2
\*Bold\*
/italic/
\_underline\_
- List item 1
- List item 2
  - Sublist item
[[Link_url][link_text]]

Cheatsheet

There are many Org-mode key stroke cheatsheets, but for markup only you can consult here

You can read more on the org-mode website.

Keyboard photo by Wouter Verhelst on Flickr
Categories
GNU/Linux Free Software & Open Source Tutorials & Tips

Quick search and replace recursively in multiple files

Lately I’ve been working with a lot of static HTML files with lots of repeating text structures. In the past I’ve talked about editing multiple files with Emacs. This approach works very well when the number of multiple files and text matches in each file is manageable or you need to make sure every match to replace is correct, since you need to confirm pressing y on every text match in each file.

In other cases, like the one I had to solve, you can have 84,000 text files where each file can have more than 5 matches. This case, doing it with Emacs wouldn’t reduce much time. It also helps that the pattern I was looking for was consistent without me needing to check every match.

So to do a quick search and replace recursively in multiple files, another “old school” tool comes very handy.

GNU Sed

Quoting from the GNU Sed project page:

Sed (streams editor) isn’t really a true text editor or text processor. Instead, it is used to filter text, i.e., it takes text input and performs some operation (or set of operations) on it and outputs the modified text. Sed is typically used for extracting part of a file using pattern matching or substituting multiple occurrences of a string within a file.

The way to tell sed to do a search and replace on some given text, the syntax is the following:

sed -n -e 's/regex/text/g' filename

The -n switch makes Sed not to output its results to the standard output and overwrite the file with the results. The -e switch specifies that the following string is a command to perform on the file. The regex part is the regular expression to use for searching in your text. The text part is the text you want to replace your search with.

So Sed receives streams of text as input, makes some operations on it and outputs the results. This way of seeing it, makes it very obvious to understand that the natural way to use it is through bash calls using pipes.

The find tool will help us get a list of all the files that we need to pipe into sed. In the same way we used find from within Emacs, we can call it from bash:

$ find path/to/folder -iname "filenamepattern"

So a combination of find with sed can be used in the following way:

$ find myprojectfolder -iname "*.html" | sed -n -e 's/searchregex/replacementtext/g'

As easy as that, and you have edited 84,000 files with one single line of bash.

Hope its useful for anyone. It has been very useful to me. If you have other methods or other sed tips, I’d like to know in the comments.