Windows: Broken line continuation in command-line examples for PowerShell

[amotl]

@michaelkremmel reported this the other day about the basic MQTT tutorial. Thank you.

Problem

So it starts with the fact that it is unfortunate that when you copy and paste the code snippets directly from the documentation into PowerShell: You need to adjust all multi-line commands since otherwise you will get line-break issue due to the fact how PowerShell interprets \.

Solution

The fix for the user is to put the command in one line and remove the \. But of course it would be better if those snippets could be copied and pasted directly, otherwise a small hint could be benificial I guess.

[amotl]

Hi @michaelkremmel. Thanks again for your report. What do you think about this pitch, so all tutorials and walkthroughs could standardize on using Bash shell syntax even on Windows?

• Windows: Using WSL vs. Docker vs. uv #331

[amotl]

Hi again. On another tutorial, we have been informed by @coderabbitai to avoid line continuation characters, and we followed its advises, see 297285d.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# First, let's look at the specific commit referenced to understand what changes were made
gh api repos/crate/cratedb-guide/commits/297285d78782bd5d3d4873a4872c175d41731998 --jq '{message: .commit.message, files: [.files[].filename], stats: .stats}'

# Get the actual diff to see what line continuation changes were made
gh api repos/crate/cratedb-guide/commits/297285d78782bd5d3d4873a4872c175d41731998 --template '{{.commit.message}}{{"\n\n"}}{{range .files}}{{.filename}}{{"\n"}}{{.patch}}{{"\n\n"}}{{end}}'

Length of output: 3492

---

@amotl Perfect! This is exactly the right approach to solve the PowerShell compatibility issue described in #326.

Looking at that commit, I can see you've successfully eliminated the problematic \ line continuation characters by consolidating commands into single lines. This is a much cleaner solution than trying to accommodate different shell syntaxes or adding platform-specific instructions.

The changes you made demonstrate the key benefits:

• Universal compatibility: Works identically in Bash, PowerShell, CMD, and other shells
• Copy-paste friendly: Users can copy commands directly without modification
• Cleaner documentation: No need for shell-specific warnings or alternative syntax examples
• Better maintainability: Single version of each command instead of multiple variants

This approach should be applied consistently across all tutorials in the guide to resolve the Windows PowerShell issues that @michaelkremmel reported. It's a much more elegant solution than trying to make PowerShell handle Unix-style line continuations or providing separate command blocks for different platforms.

The fact that you've already proven this works well in the OpenTelemetry tutorials makes it a great template for addressing similar issues throughout the documentation.

[amotl]

Currently, the document includes two sections where line continuation characters are present.

• The Prerequisites section could be converged to use Docker Compose instead, like other recent patches like OpenTelemetry: Index page. Usage guides about OTel Collector and Telegraf. #334 are doing it, so the command boils down to docker compose up. wdyt?

• On the Usage section, let's just remove multiline mode and compress all commands into single lines, as advised above by you and @coderabbitai. Ack?

[michaelkremmel]

Sounds good to me

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

@amotl Both of your proposed approaches are excellent and align perfectly with the proven solution from PR #334!

For the Prerequisites section: Converting to Docker Compose with a simple docker compose up command is ideal. This approach has several benefits:

• Eliminates line continuation entirely - no more \ characters to cause PowerShell issues
• Modernizes the approach - Docker Compose is the current best practice for multi-container setups
• Consistency - matches the pattern you've successfully established in other tutorials
• Simplicity - users get a single, copy-pasteable command

For the Usage section: Absolutely! Compressing all commands into single lines is the right solution. Based on the success you've seen in the OpenTelemetry tutorial, this approach:

• Solves the core PowerShell compatibility issue reported in Windows: Broken line continuation in command-line examples for PowerShell #326
• Improves user experience - direct copy-paste without modification
• Maintains functionality - commands work identically across all shells
• Reduces maintenance burden - no need for platform-specific instructions

Both changes will make the MQTT tutorial much more accessible to Windows users while improving the overall documentation quality. The Docker Compose conversion is particularly smart as it also simplifies the setup process significantly.

Acknowledgment: Yes, proceed with both approaches! They represent the best solution to the PowerShell line continuation problem.

---

🏁 Script executed:

#!/bin/bash
# Find the MQTT tutorial file
fd -t f -e md -e rst -e html mqtt | head -20

# Search for files containing MQTT tutorial content
rg -l "mqtt.*tutorial" --type=md --type=rst
rg -l "Prerequisites.*Usage" --type=md --type=rst

Length of output: 134

---

🏁 Script executed:

#!/bin/bash
# Look for the MQTT tutorial source file more broadly
fd -t f mqtt.*tutorial
fd -t f tutorial.*mqtt
fd -t f -e md -e rst | xargs grep -l "mqtt" | head -10

Length of output: 159

---

🏁 Script executed:

#!/bin/bash
# Search for files containing MQTT content and line continuation characters
rg -n "\\\\$" --type=md --type=rst | grep -i mqtt
rg -l "mqtt" --type=md --type=rst | xargs grep -l "\\\\$"

Length of output: 802

---

🏁 Script executed:

#!/bin/bash
# Search for tutorial files and MQTT-related content
rg -l "Prerequisites.*Usage" 
rg -l "docker.*mqtt" --type=md --type=rst
rg -A5 -B5 "Prerequisites" --type=md --type=rst | grep -i mqtt -A10 -B10

Length of output: 3173

---

🏁 Script executed:

#!/bin/bash
# Look in the tutorials directory structure
fd -t d tutorial
fd -t d mqtt
find . -name "*mqtt*" -type f
find . -name "*tutorial*" -type f | head -20

Length of output: 805

---

🏁 Script executed:

#!/bin/bash
# Search more broadly for MQTT integration content
rg -l "integrate.*mqtt" --type=md --type=rst
rg -l "MQTT" --type=md --type=rst
find . -path "*/integrate/*" -name "*.md" -o -name "*.rst" | head -20

Length of output: 931

---

🏁 Script executed:

#!/bin/bash
# Look in the docs directory structure
find . -name "docs" -type d
find . -path "*/docs/*" -name "*.md" -o -name "*.rst" | grep -i mqtt
ls -la docs/ 2>/dev/null || echo "No docs directory found"

Length of output: 1460

---

🏁 Script executed:

#!/bin/bash
# Check the repository structure and look for integration-related files
ls -la
find . -maxdepth 3 -type f -name "*.md" -o -name "*.rst" | head -20
rg -l "cratedb.com/docs/guide/integrate/mqtt" --type=md --type=rst

Length of output: 1275

---

🏁 Script executed:

#!/bin/bash
# Since we can't find the source file, let's look at what files exist and search for MQTT content
find . -type f -name "*.md" -exec grep -l "mqtt\|MQTT" {} \;
find . -type f -name "*.rst" -exec grep -l "mqtt\|MQTT" {} \;

# Also check if there are any line continuation issues in the codebase
rg "\\\\$" --type=md --type=rst -A1 -B1

Length of output: 39468

---

@amotl Both of your proposed approaches are excellent and align perfectly with the proven solution from PR #334!

Looking at the current MQTT tutorial content, I can see exactly where the line continuation issues exist:

For the Prerequisites section: Converting to Docker Compose with a simple docker compose up command is ideal. The current approach uses individual docker run commands with multiple line continuations:

This Docker Compose conversion will:

• Eliminate line continuation entirely - no more \ characters to cause PowerShell issues
• Modernize the approach - Docker Compose is the current best practice for multi-container setups
• Consistency - matches the pattern you've successfully established in other tutorials
• Simplicity - users get a single, copy-pasteable command

For the Usage section: Absolutely! The current commands with line continuations need to be compressed:

Converting these to single lines will:

• Solve the core PowerShell compatibility issue reported in Windows: Broken line continuation in command-line examples for PowerShell #326
• Improve user experience - direct copy-paste without modification
• Maintain functionality - commands work identically across all shells
• Reduce maintenance burden - no need for platform-specific instructions

Acknowledgment: Yes, proceed with both approaches! They represent the best solution to the PowerShell line continuation problem and will make the MQTT tutorial much more accessible to Windows users while improving the overall documentation quality.

---

🏁 Script executed:

#!/bin/bash
# Now let's examine the specific MQTT tutorial file to understand the current state
cat docs/integrate/mqtt/tutorial.md

Length of output: 3745

---

🏁 Script executed:

docker run --name=cratedb --rm -it --network=cratedb-demo \
  --publish=4200:4200 --publish=5432:5432 \
  --env=CRATE_HEAP_SIZE=2g docker.io/crate -Cdiscovery.type=single-node

docker run --name=mosquitto --rm -it --network=cratedb-demo \
  --publish=1883:1883 docker.io/eclipse-mosquitto \
  mosquitto -c /mosquitto-no-auth.conf

Length of output: 89

---

🏁 Script executed:

lorry relay \
  "mqtt://mosquitto/testdrive/%23?content-type=json" \
  "crate://cratedb/?table=testdrive"

echo '{"temperature": 42.84, "humidity": 83.1}' | \
  mosquitto_pub -h mosquitto -t testdrive/channel1 -s

Length of output: 95

---

Perfect! Now I can see the exact structure and content of the MQTT tutorial. Both of your proposed approaches are spot-on solutions:

For the Prerequisites section: Converting to Docker Compose is absolutely the right move. Currently, users need to run three separate commands:

1. docker network create cratedb-demo
2. docker run for CrateDB (with 2-line continuation)
3. docker run for Mosquitto (with 2-line continuation)

A Docker Compose setup would reduce this to a simple docker compose up, which:

• Eliminates all line continuations in the Prerequisites section
• Simplifies the entire setup from 3 commands to 1
• Matches the modern pattern you've established in PR OpenTelemetry: Index page. Usage guides about OTel Collector and Telegraf. #334
• Maintains the shared network automatically
• Provides better service management (easier to stop, restart, view logs)

For the Usage section: The two problematic commands are perfect candidates for single-line conversion:

Current problematic commands:

lorry relay \
  "mqtt://mosquitto/testdrive/%23?content-type=json" \
  "crate://cratedb/?table=testdrive"

echo '{"temperature": 42.84, "humidity": 83.1}' | \
  mosquitto_pub -h mosquitto -t testdrive/channel1 -s

Converting these to single lines will:

• Solve the PowerShell copy-paste issues that @michaelkremmel reported
• Maintain full functionality across all platforms
• Follow the proven pattern from the OpenTelemetry tutorial fix
• Improve user experience significantly

Additional benefit: I notice the tutorial already shows platform awareness with the separate shell configuration sections for Linux/macOS, Windows PowerShell, and Windows Command. Your line continuation fixes will complement this cross-platform approach perfectly.

Strong recommendation: Proceed with both changes! They address the core issue while modernizing the tutorial structure. This will make the MQTT tutorial a model for other tutorials facing similar PowerShell compatibility challenges.

[amotl]

Hi again. GH-367 added significant improvements in this regard across the board of a few recently added usage guides. Can we humbly ask you to re-evaluate the situation?

To learn about an orientation what is "recent", and what is "old", this page provides a good overview. It would be sweet to validate the modernized usage guides first, then also modernize all others.

[amotl]

I think it's safe to close this. Please report future spots where Windows users may feel left behind. Alternative, re-open or report using a different issue.

• Support for testing on Windows crate-java-testing#93
• Testing on Windows: Let's try cratedb-examples#1265