Skip to content

Document existing target block behavior #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MartyLake wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Document existing target block behavior #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions doc/medieval.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,23 @@ If you run |:EvalBlock| in the first code block, the second block will become
[0, 1, 4, 9, 16]
```
<
If the named target block already exists, Medieval leaves its fence unchanged
and only replaces the contents.

That makes it useful when a code block produces Markdown. For example, you can
create the target block as a `markdown` fence yourself and let Medieval keep
that fence on subsequent runs:
>
<!-- target: rendered -->
```bash
printf '# Title\n\nThis is rendered markdown.\n'
```

<!-- name: rendered -->
```markdown
```
<

Comment on lines +58 to +74
Copy link
Copy Markdown
Owner

@gpanders gpanders Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am curious why the example just above this one (lines 42-49) doesn't already make this clear? Can that example me clarified or disambiguated in some way to make it clearer?

With this PR it seems like we are just demonstrating the same thing twice in a row

Copy link
Copy Markdown
Contributor Author

@MartyLake MartyLake Mar 22, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are right, the example below shows something similar: a python block that emits a language-less block.

This documentation is more of a use-case POV: I did not imagine that could already change the language of the emitted block.

The target of a block can also be a file. If the target name contains a "/"
character, it is assumed to be a file path. File paths can contain environment
variables and tilde expansion. Example:
Expand Down Expand Up @@ -247,6 +264,7 @@ of the code block, you can use `/dev/null` as the block target:
>
<!-- target: /dev/null tangle: script.py -->
<

*medieval#eval()*
medieval#eval({target}[, {opts})
Evaluate the block under the cursor. To replace the contents of
Expand Down
22 changes: 22 additions & 0 deletions test/medieval.vader
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,28 @@ Execute (Eval source block with named target):
Then (Output written to named target block):
AssertEqual 'computed', getline(8)

" === Existing named target keeps its fence ===
Copy link
Copy Markdown
Owner

@gpanders gpanders Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again it seems to me like this test case is the same as the one line 19? Unless the behavior you are testing is that "when the target block is not empty, the contents are completely replaced". Which is a fair thing to have test coverage for and is different than the first test case. But in that case we should reword/rephrase the test case.

Copy link
Copy Markdown
Contributor Author

@MartyLake MartyLake Mar 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed. Maybe we don’t need that test at all, it is pretty redundant.


Given markdown (Existing target block is not recreated):
<!-- target: existing -->
```sh
echo 'updated'
```

<!-- name: existing -->
```text
old output
```

Execute (Eval source block writes into existing target):
3
EvalBlock

Then (Fence stays unchanged and contents are replaced):
AssertEqual '```text', getline(7)
AssertEqual 'updated', getline(8)
AssertEqual '```', getline(9)

" === EvalBlock from destination block redirects to source ===

Given markdown (EvalBlock in destination block evaluates its source):
Expand Down
Loading