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
Emacs GNU/Linux Free Software & Open Source

Emacs tip: How to edit multiple files on several directories in less than a minute

Recently I had to edit multiple files (239 in total) scattered in a bunch of directories and subdirectories. Here’s a quick and safe way to do it.

What I had to do was add the Google Analytics script snippet to a part of a website that was being maintained by a pair of <your favorite bad adjective here> developers.

So, first I thought of using sed or awk or something like that, but doing a quick search replace like that without checking if my match is correct in every instance in a bunch of files can lead to a big disaster.

But wait, I have Emacs! So, the first thing to do is find and list all the files you need to edit.

  1. Open the parent directory

    Use dired to open the parent directory where all the files and directories are. Open dired with:

    M-x find-dired


    and enter the path for the directory.

  2. Find the files

    Emacs will then prompt: “Run find (with args):”. So if you need to edit all HTML files, or in my case, PHP files, you type:

    -name "*.php"

    If you want all files regardless of type, enter

    -type f


    Basically you can type in any arguments you want if you know how to use the find command.

  3. Mark the files you need to edit

    A list of all found files will appear in a dired buffer. Now you need to mark the files you want to work with. Typically you’ll mark all files since you already filtered them. Press t to toggle marks and all files will get marked. Or if you want to hand pick them, move the cursor to the file line or name and press m.

  4. Do the find and replace

    Type: Press Q or M-x dired-do-query-replace-regexp to run the find and replace command. It will prompt you first for the text you want to find, then will prompt you with the text you want to replace it with.

    Then Emacs will start the find and replace operation, and will prompt you on every find if you want to replace the text or skip it. To replace, type y, to skip to the next find type n. To replace all occurrences without asking, type !. To cancel the operation, type C-g.

  5. Save the edited files

    Now that you’ve made all these changes, you need to save the files. To avoid saving manually all files, you can open ibuffer

    M-x ibuffer

    Which will list all you opened files (called buffers). Now, like in dired, you need to mark the buffers you want to work with. To mark all unsaved files, type * u and then type S (that’s shift+s, for the capital letter) to save them.

Done!

Easy and without a sweat.

photo by zyphichore on Flickr.