From ec6a9d31dfd2679d01b8a074d56a2e6091c0c5f1 Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Wed, 25 Apr 2018 09:11:39 +0200 Subject: [PATCH] implement #src tag instead of trailing #jl --- docs/src/fileformat.md | 28 ++++++++++++++++++++-------- examples/example.jl | 11 ++++++----- src/Literate.jl | 7 ++++--- test/runtests.jl | 6 ++---- 4 files changed, 32 insertions(+), 20 deletions(-) diff --git a/docs/src/fileformat.md b/docs/src/fileformat.md index 4097296..5716d94 100644 --- a/docs/src/fileformat.md +++ b/docs/src/fileformat.md @@ -35,8 +35,8 @@ julia code. We note a couple of things: thus serve as good documentation on its own. For simple use this is all you need to know. The following additional special syntax can also be used: -- `#md`, `#nb`, `#jl`: tags for filtering of lines, see [Filtering Lines](@ref Filtering-Lines). -- `#-`: tag for manually controlling chunk-splits, see [Custom control over chunk splits](@ref). +- `#md`, `#nb`, `#jl`, `#src`: tags to filter lines, see [Filtering Lines](@ref Filtering-Lines), +- `#-`: tag to manually control chunk-splits, see [Custom control over chunk splits](@ref). There is also some default convenience replacements that will always be performed, see [Default Replacements](@ref). @@ -44,13 +44,15 @@ There is also some default convenience replacements that will always be performe ## [**2.2.** Filtering Lines](@id Filtering-Lines) -It is possible to filter out lines depending on the output format. For this purpose, -there are three different "tokens" that can be placed on the start of the line: -- `#md`: markdown output only, -- `#nb`: notebook output only, -- `#jl`: script output only. +It is often useful to filter out lines in the source depending on the output format. +For this purpose there are a number of "tokens" that can be used to mark the purpose of +certain lines: +- `#md `: line exclusive to markdown output, +- `#nb `: line exclusive to notebook output, +- `#jl `: line exclusive to script output, +- `#src `: line exclusive to the source code and thus filtered out unconditionally. -Lines starting with one of these tokens are filtered out in the +Lines *starting* with one of these tokens are filtered out in the [preprocessing step](@ref Pre-processing). Suppose, for example, that we want to include a docstring within a `@docs` block @@ -68,6 +70,16 @@ The lines in the example above would be filtered out in the preprocessing step, generating a markdown file. When generating a markdown file we would simple remove the leading `#md ` from the lines. Beware that the space after the tag is also removed. +The `#src` token can also be placed at the *end* of a line. This is to make it possible +to have code lines exclusive to the source code, and not just comment lines. For example, +if the source file is included in the test suite we might want to add a `@test` at the end +without this showing up in the outputs: + +```julia +using Test #src +@test result == expected_result #src +``` + ## [**2.3.** Default Replacements](@id Default-Replacements) diff --git a/examples/example.jl b/examples/example.jl index 1382160..34d1eec 100644 --- a/examples/example.jl +++ b/examples/example.jl @@ -25,11 +25,12 @@ y = 2//5 #' write *text in italic font*, **text in bold font** and use #' [links](https://www.youtube.com/watch?v=dQw4w9WgXcQ). -#' It is possible to filter lines by starting it with `#md`, `#nb` or `#jl` -#' for markdown, notebook and script output only, respectively. -#md #' This line is filtered out for notebook and script output. -#nb #' This line is filtered out for markdown and script output. -#jl #' This line is filtered out for markdown and notebook output. +#' It is possible to filter out lines depending on the output using the +#' `#md`, `#nb`, `#jl` and `#src` tags (see [Filtering Lines](@ref)): +#md #' - This line starts with `#md` and is thus only visible in the markdown output. +#nb #' - This line starts with `#nb` and is thus only visible in the notebook output. +#jl #' - This line starts with `#jl` and is thus only visible in the notebook output. +#src #' - This line starts with `#src` and is thus only visible in the source file. #' The source file is parsed in chunks of markdown and code. Starting a line #' with `#-` manually inserts a chunk break. For example, if we want to diff --git a/src/Literate.jl b/src/Literate.jl index 32689ae..179ebfc 100644 --- a/src/Literate.jl +++ b/src/Literate.jl @@ -139,22 +139,23 @@ function replace_default(content, sym; push!(repls, "\r\n" => "\n") # normalize line endings + # unconditionally remove #src lines + push!(repls, r"^#src.*\n?"m => "") + push!(repls, r".*#src$\n?"m => "") + if sym === :md push!(repls, r"^#nb.*\n?"m => "") # remove #nb lines push!(repls, r"^#jl.*\n?"m => "") # remove leading #jl lines - push!(repls, r".*#jl$\n?"m => "") # remove trailing #jl lines push!(repls, r"^#md "m => "") # remove leading #md elseif sym === :nb push!(repls, r"^#md.*\n?"m => "") # remove #md lines push!(repls, r"^#jl.*\n?"m => "") # remove leading #jl lines - push!(repls, r".*#jl$\n?"m => "") # remove trailing #jl lines push!(repls, r"^#nb "m => "") # remove leading #nb push!(repls, r"```math(.*?)```"s => s"\\begin{equation}\1\\end{equation}") else # sym === :jl push!(repls, r"^#md.*\n?"m => "") # remove #md lines push!(repls, r"^#nb.*\n?"m => "") # remove #nb lines push!(repls, r"^#jl "m => "") # remove leading #jl - push!(repls, r" #jl$"m => "") # remove trailing #jl end # name diff --git a/test/runtests.jl b/test/runtests.jl index 7d9ac05..e57049b 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -147,8 +147,8 @@ content = """ #nb x + 2 #jl #' Only script #jl x + 3 - #' Only script too #jl - x + 4 #jl + #src #' Source code only + Source code only #src # #' Comment # another comment #- @@ -192,8 +192,6 @@ content = """ x = 1 x + 3 - - x + 4 # #' Comment # another comment