[mirfalltnixein]

I, the human behind this, have run into this problem. I've reviewed this code and am willing to put my name on it.

Fixes #367
Fixes #368

Problem

When stdout is not a terminal (e.g. tldr tar | cat):

• Nonsense output at the end of tldr when piped #367: the page comes out scrambled: each description and example line is joined onto the next one, and all the newlines are printed at the end. (The "null byte" in Nonsense output at the end of tldr when piped #367 is hexdump padding the odd-length output; od -c shows none.)
• Piping tldr does not strip all style #368: the italics around backticked text in example descriptions are still printed, although the client specification says: "If not [a TTY], then the output MUST not contain any additional decorations."

Cause

• output() writes the page lines with sys.stdout.buffer.write() (raw bytes, added in improve handling of different languages #112 so pages are always UTF-8) but the newlines with print(). print() goes through the text layer, which has its own buffer. On a terminal that buffer is flushed every line, so the order looks right; on a pipe it is block-buffered, so all the print() newlines arrive after the byte writes.
• The italics are raw \x1B[3m / \x1B[23m escapes, added around colored(), so they are emitted even when termcolor has decided not to color the output.

The existing test_whole_page replaces sys.stdout.buffer with a stub that writes into the same StringIO as print(), which is why it never showed up in the tests.

Fix

• output() writes everything as bytes, including the --markdown lines (otherwise they would be reordered against the final newline), and flushes pending text output first so messages printed before the page (e.g. the TLDR_PLATFORM warning) stay in front of it.
• emphasise_example only adds the italics when colored() actually styled the text. (termcolor has an italic attribute only since 3.3.0, so I didn't rely on it.)
• New test test_whole_page_piped renders the gem and jq pages in a subprocess through a real pipe, with and without FORCE_COLOR. Without colors, the expected output is the rendered file with all ANSI codes stripped. It skips the no-color case on termcolor < 2.1, which doesn't disable colors when not on a TTY.

One behavior change: on Windows, the newlines written by output() are now \n instead of print()'s \r\n. The page lines themselves already bypassed the text layer.

Testing

• pytest: 35 passed on Python 3.10 and 3.14; with termcolor 1.1.0 and 2.0.0, 33 passed and the 2 no-color cases skipped; 2.1.0, 2.4.0 and 3.3.0 all pass. flake8 clean.
• The 4 new test cases fail on current main, and also fail if the sys.stdout.flush() is removed.
• tldr tar | cat -A now prints the page line by line with no escape codes; FORCE_COLOR=1 tldr echo | cat -A keeps the colors and italics.

I used an AI assistant (Claude Code) to write this change. I reviewed the code and the tests before submitting.

🤖 Generated with Claude Code