Add .byLine Windows Example: Update stdio.d

[BoQsc]

[dlang-bot]

Thanks for your pull request and interest in making D better, @BoQsc! We are looking forward to reviewing it, and you should be hearing from a maintainer soon. Please verify that your PR follows this checklist:

• My PR is fully covered with tests (you can see the coverage diff by visiting the details link of the codecov check)
• My PR is as minimal as possible (smaller, focused PRs are easier to review than big ones)
• I have provided a detailed rationale explaining my changes
• New or modified functions have Ddoc comments (with Params: and Returns:)

Please see CONTRIBUTING.md for more information.

---

If you have addressed all reviews or aren't sure how to proceed, don't hesitate to ping us with a simple comment.

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

Testing this PR locally

If you don't have a local development environment setup, you can use Digger to test this PR:

dub run digger -- build "master + phobos#8860"

[BoQsc]

It's not clear to me what exactly the Windows specific example demonstrates.

It demonstrates the use of .byLine parameters and ability to disable terminators on Windows (.byLine(No.keepTerminator, "\r\n")). \r Return Carriage is specific to Windows. Here is forum thread: https://forum.dlang.org/post/[email protected]

What does "^This Line is here." mean?

The if statement compares the text to the line in the file. It's just a notice that matching content is found using the if statement.

The ^ is only a visual cue and is not necessary.
Can be removed to avoid such questions in the future. Personally I would leave it as it is.

[dkorpel]

Ah, I get it now, I've been bitten by the \r terminator appearing in my strings on Windows too.

The documentation of terminator already mentions:

Use $(REF newline, std,ascii) for portability (unless the file was opened in text mode).

I think the correct thing to do is open the file in text mode in the documentation examples, and explain that it's needed to convert "\r\n" to "\n" on Windows so there's no trailing '\r' on each line. A Windows-specific hard coded example might encourage people to needlessly write non-portable code.

[BoQsc]

Ah, I get it now, I've been bitten by the \r terminator appearing in my strings on Windows too.

The documentation of terminator already mentions:

Use $(REF newline, std,ascii) for portability (unless the file was opened in text mode).

I think the correct thing to do is open the file in text mode in the documentation examples, and explain that it's needed to convert "\r\n" to "\n" on Windows so there's no trailing '\r' on each line. A Windows-specific hard coded example might encourage people to needlessly write non-portable code.

It's my second time encountering this issue, and I feel like introducing concrete example is reflective and ensuring. It saves time and it's possible to quickly test. Yes, having supporting notes is very good idea as well.

Overall lack of examples in the documentation really discourages programming and effective understanding. Which might lead to less adoption of the language.

Let the people decide if they want portable code or not, instead of limiting. Sometimes portable code is incomplete or wrong.

[dkorpel]

Those are good general observations, but I don't see how they apply here.

Overall lack of examples in the documentation really discourages programming and effective understanding.

There's no lack in quantity of examples of byLine, there's a lack of quality.

Let the people decide if they want portable code or not, instead of limiting.

People can still write non-portable code if they want, but the documentation should have good examples, not examples of bad practice.

Sometimes portable code is incomplete or wrong.

Then that code should be fixed. In this case, I don't see what's wrong with opening the file in text mode or using a portable newline string.

[dkorpel]

If you really want a Windows only example, the code should be in a version (Windows) block, and include an explanation what the code does, why it might not work on other platforms than Windows, and what to do to make it portable.