{
 "cells": [
  {
   "outputs": [],
   "cell_type": "markdown",
   "source": [
    "# **7.** Example\n",
    "\n",
    "This is an example generated with Literate based on this\n",
    "source file: [`example.jl`](https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl).\n",
    "You are seeing the\n",
    "generated notebook output. The corresponding markdown (html) output\n",
    "can be found here: [`example.html`](https://fredrikekre.github.io/Literate.jl/latest/generated/example.html),\n",
    "and the plain script output can be found here: [`example.jl`](./example.jl)."
   ],
   "metadata": {}
  },
  {
   "outputs": [],
   "cell_type": "markdown",
   "source": [
    "It is recommended to have the [source file](https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl)\n",
    "available when reading this, to better understand how the syntax in the source file\n",
    "corresponds to the output you are seeing."
   ],
   "metadata": {}
  },
  {
   "outputs": [],
   "cell_type": "markdown",
   "source": [
    "### Basic syntax\n",
    "The basic syntax for Literate is simple, lines starting with `#'` is interpreted\n",
    "as markdown, and all the other lines are interpreted as code. Here is some code:"
   ],
   "metadata": {}
  },
  {
   "outputs": [
    {
     "output_type": "execute_result",
     "data": {
      "text/plain": "2//5"
     },
     "metadata": {},
     "execution_count": 1
    }
   ],
   "cell_type": "code",
   "source": [
    "x = 1//3\n",
    "y = 2//5"
   ],
   "metadata": {},
   "execution_count": 1
  },
  {
   "outputs": [],
   "cell_type": "markdown",
   "source": [
    "In markdown sections we can use markdown syntax. For example, we can\n",
    "write *text in italic font*, **text in bold font** and use\n",
    "[links](https://www.youtube.com/watch?v=dQw4w9WgXcQ)."
   ],
   "metadata": {}
  },
  {
   "outputs": [],
   "cell_type": "markdown",
   "source": [
    "It is possible to filter out lines depending on the output using the\n",
    "`#md`, `#nb`, `#jl` and `#src` tags (see Filtering Lines):\n",
    "- This line starts with `#nb` and is thus only visible in the notebook output."
   ],
   "metadata": {}
  },
  {
   "outputs": [],
   "cell_type": "markdown",
   "source": [
    "The source file is parsed in chunks of markdown and code. Starting a line\n",
    "with `#-` manually inserts a chunk break. For example, if we want to\n",
    "display the output of the following operations we may insert `#-` in\n",
    "between. These two code blocks will now end up in different\n",
    "`@example`-blocks in the markdown output, and two different notebook cells\n",
    "in the notebook output."
   ],
   "metadata": {}
  },
  {
   "outputs": [
    {
     "output_type": "execute_result",
     "data": {
      "text/plain": "11//15"
     },
     "metadata": {},
     "execution_count": 2
    }
   ],
   "cell_type": "code",
   "source": [
    "x + y"
   ],
   "metadata": {},
   "execution_count": 2
  },
  {
   "outputs": [
    {
     "output_type": "execute_result",
     "data": {
      "text/plain": "2//15"
     },
     "metadata": {},
     "execution_count": 3
    }
   ],
   "cell_type": "code",
   "source": [
    "x * y"
   ],
   "metadata": {},
   "execution_count": 3
  },
  {
   "outputs": [],
   "cell_type": "markdown",
   "source": [
    "### Output Capturing\n",
    "Code chunks are by default placed in Documenter `@example` blocks in the generated\n",
    "markdown. This means that the output will be captured in a block when Documenter is\n",
    "building the docs. In notebooks the output is captured in output cells, if the\n",
    "`execute` keyword argument is set to true. Output to `stdout`/`stderr` is also\n",
    "captured."
   ],
   "metadata": {}
  },
  {
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This string is printed to stdout.\n"
     ]
    },
    {
     "output_type": "execute_result",
     "data": {
      "text/plain": "4-element Array{Int64,1}:\n 1\n 2\n 3\n 4"
     },
     "metadata": {},
     "execution_count": 4
    }
   ],
   "cell_type": "code",
   "source": [
    "function foo()\n",
    "    println(\"This string is printed to stdout.\")\n",
    "    return [1, 2, 3, 4]\n",
    "end\n",
    "\n",
    "foo()"
   ],
   "metadata": {},
   "execution_count": 4
  },
  {
   "outputs": [],
   "cell_type": "markdown",
   "source": [
    "### Custom processing\n",
    "\n",
    "It is possible to give Literate custom pre- and post-processing functions.\n",
    "For example, here we insert two placeholders, which we will replace with\n",
    "something else at time of generation. We have here replaced our placeholders\n",
    "with `z` and `1.0 + 2.0im`:"
   ],
   "metadata": {}
  },
  {
   "outputs": [
    {
     "output_type": "execute_result",
     "data": {
      "text/plain": "1.0 + 2.0im"
     },
     "metadata": {},
     "execution_count": 5
    }
   ],
   "cell_type": "code",
   "source": [
    "z = 1.0 + 2.0im"
   ],
   "metadata": {},
   "execution_count": 5
  },
  {
   "outputs": [],
   "cell_type": "markdown",
   "source": [
    "### Documenter.jl interaction\n",
    "\n",
    "In the source file it is possible to use Documenter.jl style references,\n",
    "such as `@ref` and `@id`. These will be filtered out in the notebook output.\n",
    "For example, here is a link, but it is only\n",
    "visible as a link if you are reading the markdown output. We can also\n",
    "use equations:\n",
    "\n",
    "\\begin{equation}\n",
    "\\int_\\Omega \\nabla v \\cdot \\nabla u\\ \\mathrm{d}\\Omega = \\int_\\Omega v f\\ \\mathrm{d}\\Omega\n",
    "\\end{equation}\n",
    "\n",
    "using Documenters math syntax. Documenters syntax is automatically changed to\n",
    "`\\begin{equation} ... \\end{equation}` in the notebook output to display correctly."
   ],
   "metadata": {}
  },
  {
   "outputs": [],
   "cell_type": "markdown",
   "source": [
    "*This notebook was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*"
   ],
   "metadata": {}
  }
 ],
 "nbformat_minor": 3,
 "metadata": {
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "0.6.2"
  },
  "kernelspec": {
   "name": "julia-0.6",
   "display_name": "Julia 0.6.2",
   "language": "julia"
  }
 },
 "nbformat": 4
}