mirrors/jj
1
0
Fork 1
mirror of https://github.com/martinvonz/jj.git synced 2025-01-19 19:08:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: in jj help util exec, use Markdown warning admonition

Browse source 
We're scraping the CLI help text and rendering it as markdown, so we can use an "admonition" to have this warning text render nicer in the web documentation.

You could argue that `!!! warning` is a little weird to see on the CLI. Some alternatives:

- We could opt to not design the CLI help text around markdown and skip the change to the `jj util exec` help in this commit.
- We could adopt some kind of format that can be rendered well in both contexts.
  - Could sticking to specific formatting constructs by convention.
  - Could use/create an actual translation tool from CLI format to Markdwon.
- We could keep separate versions of web and CLI documentation. (Seems like a bad idea for the foreseeable future, because we don't have the resources to constantly keep both up-to-date and sync.)

I'm in favor of just writing Markdown in the CLI help text for now.
This commit is contained in:
Waleed Khan 2024-12-07 12:43:35 -08:00
parent da3c75b3cb
commit ed84468cb8
2 changed files with 12 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
cli/src/commands/util/exec.rs
View file

@ -22,13 +22,13 @@ use crate::ui::Ui;
///
/// This is useful for arbitrary aliases.
///
/// !! WARNING !!
/// !!! warning
///
/// The following technique just provides a convenient syntax for running
/// arbitrary code on your system. Using it irresponsibly may cause damage
/// ranging from breaking the behavior of `jj undo` to wiping your file system.
/// Exercise the same amount of caution while writing these aliases as you would
/// when typing commands into the terminal!
/// The following technique just provides a convenient syntax for running
/// arbitrary code on your system. Using it irresponsibly may cause damage
/// ranging from breaking the behavior of `jj undo` to wiping your file
/// system. Exercise the same amount of caution while writing these aliases
/// as you would when typing commands into the terminal!
///
/// This feature may be removed or replaced by an embedded scripting language in
/// the future.

13
cli/tests/cli-reference@.md.snap
View file

@ -1,7 +1,6 @@
---
source: cli/tests/test_generate_md_cli_help.rs
description: "AUTO-GENERATED FILE, DO NOT EDIT. This cli reference is generated by a test as an `insta` snapshot. MkDocs includes this snapshot from docs/cli-reference.md."
snapshot_kind: text
---
<!-- BEGIN MARKDOWN-->
@ -2215,13 +2214,13 @@ Execute an external command via jj
This is useful for arbitrary aliases.
!! WARNING !!
!!! warning
The following technique just provides a convenient syntax for running
arbitrary code on your system. Using it irresponsibly may cause damage
ranging from breaking the behavior of `jj undo` to wiping your file system.
Exercise the same amount of caution while writing these aliases as you would
when typing commands into the terminal!
The following technique just provides a convenient syntax for running
arbitrary code on your system. Using it irresponsibly may cause damage
ranging from breaking the behavior of `jj undo` to wiping your file
system. Exercise the same amount of caution while writing these aliases
as you would when typing commands into the terminal!
This feature may be removed or replaced by an embedded scripting language in
the future.