# one-ox | src-block

## Code highlighting with htmlize

### Description

`one-ox` highlights code via the function `one-ox-htmlize` that uses htmlize to do the work.

For a given piece of code `X` in a certain language `Y`, `X` will be highlighted as it would be in the emacs mode `Z` used to edit `Y` code.

For instance, `clojure-mode` is used to highlight Clojure code and `sh-mode` is used to highlight Bash code.

Attributes of a face (like `background-color` or `foreground-color`) are not taken directly. A generated name for the face is produced and used as the CSS class for the parts of the code `X` that are highlighted with that face.

For instance, in `sh-mode`, the word `echo` is highlighted with the face `font-lock-builtin-face`. So, the word `echo` in a piece of Shell (or Bash) code will be transformed into:

    <span class="one-hl-builtin">echo</span>

The whole piece of code `X`, once the previously described operations have been done, is wrapped:

1. for a normal block with the component:

       <pre><code class="one-hl one-hl-block">...</code></pre>

2. for a result block with the component:

       <pre><code class="one-hl one-hl-results">...</code></pre>

   See section org keyword RESULTS.

### Example with Bash code

For instance, the following org src-block, containing some `bash` code:

    #+BEGIN_SRC bash
    echo "list file's extensions in current dir:"
    for f in `ls`; do
        echo ${f##*.}
    done
    #+END_SRC

is exported as follow:

    <pre><code class="one-hl one-hl-block"><span class="one-hl-builtin">echo</span> <span class="one-hl-string">"list file's extensions in current dir:"</span>
    <span class="one-hl-keyword">for</span> f<span class="one-hl-keyword"> in</span> <span class="one-hl-sh-quoted-exec">`ls`</span>; <span class="one-hl-keyword">do</span>
        <span class="one-hl-builtin">echo</span> ${<span class="one-hl-variable-name">f</span>##*.}
    <span class="one-hl-keyword">done</span></code></pre>
    </div>

and rendered like this:

    echo "list file's extensions in current dir:"
    for f in `ls`; do
        echo ${f##*.}
    done

Note that `one-ox-htmlize` has produced and used the following CSS classes (listed with their corresponding emacs faces):

    # from font-lock
    one-hl-builtin        --> font-lock-builtin-face
    one-hl-keyword        --> font-lock-keyword-face
    one-hl-string         --> font-lock-string-face
    one-hl-variable-name  --> font-lock-variable-name-face

    # specific to sh-mode
    one-hl-sh-quoted-exec --> sh-quoted-exec

You might have notice the pattern used for `font-lock` faces and the one used for mode specific faces.

`one.el` provides a default style sheet (`one-default-css`) that has the CSS classes defined for all the `font-lock` faces (faces starting by `font-lock-`) but not the specific faces used by each prog mode.

You can add the CSS classes specific to the prog modes you use as you go and need them.

## Org keyword RESULTS

Result blocks are preceded by a line starting with `#+RESULTS:`. Blocks that are not result blocks are normal blocks.

When exported, normal blocks and result blocks differ only by their CSS classes:

- `one-hl one-hl-block` for normal blocks,

- `one-hl one-hl-results` for result blocks.

This way result blocks can be rendered with a different style than normal blocks as we can see in the following example.

### Example using org keyword 'RESULTS'

The following org snippet:

    #+BEGIN_SRC bash :results output
    ls
    #+END_SRC

    #+RESULTS:
    : assets
    : docs.org
    : public

is exported by `one-ox` as follow:

    <pre><code class="one-hl one-hl-block">ls</code></pre>
    <pre><code class="one-hl one-hl-results">assets
    docs.org
    public</code></pre>

and is rendered by `one-ox` with the first block (normal block) having a different style from second block (result block):

    ls

    assets
    docs.org
    public

## Code blocks inside list

Lists can contain source blocks as we can see in the following org snippet

    1. item 1

       #+BEGIN_SRC emacs-lisp
       (message "src-block in item 1")
       #+END_SRC

    2. item 2
    3. item 3

which is exported by `one` as follow

    <ol>
      <li>
        <p>item 1</p>
        <pre><code class="one-hl one-hl-block">(message <span class="one-hl-string">"src-block in item 1"</span>)</code></pre>
      </li>
      <li><p>item 2</p></li>
      <li><p>item 3</p></li>
    </ol>

and is rendered by `one-ox` like this:

1. item 1

       (message "src-block in item 1")

2. item 2

3. item 3