implement #src tag instead of trailing #jl

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).
+- `#md`, `#nb`, `#jl`, `#src`: tags to filter lines, see [Filtering Lines](@ref Filtering-Lines),
-- `#-`: tag for manually controlling chunk-splits, see [Custom control over chunk splits](@ref).
+- `#-`: 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,
+It is often useful to filter out lines in the source depending on the output format.
-there are three different "tokens" that can be placed on the start of the line:
+For this purpose there are a number of "tokens" that can be used to mark the purpose of
-- `#md`: markdown output only,
+certain lines:
-- `#nb`: notebook output only,
+- `#md `: line exclusive to markdown output,
-- `#jl`: script output only.
+- `#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)
 

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`
+#' It is possible to filter out lines depending on the output using the
-#' for markdown, notebook and script output only, respectively.
+#' `#md`, `#nb`, `#jl` and `#src` tags (see [Filtering Lines](@ref)):
-#md #' This line is filtered out for notebook and script output.
+#md #' - This line starts with `#md` and is thus only visible in the markdown output.
-#nb #' This line is filtered out for markdown and script output.
+#nb #' - This line starts with `#nb` and is thus only visible in the notebook output.
-#jl #' This line is filtered out for markdown and 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

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

test/runtests.jl

@@ -147,8 +147,8 @@ content = """
     #nb x + 2
     #jl #' Only script
     #jl x + 3
-    #' Only script too  #jl
+    #src #' Source code only
-    x + 4               #jl
+    Source code only          #src
     # #' Comment
     # another comment
     #-
@@ -192,8 +192,6 @@ content = """
             x = 1
 
             x + 3
-
-            x + 4
             # #' Comment
             # another comment