View Issue Details
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0037692||FPC||Documentation||public||2020-09-02 20:55||2020-09-02 23:56|
|Reporter||Will B||Assigned To||Michael Van Canneyt|
|Fixed in Version||3.3.1|
|Summary||0037692: Documentation for Write needs small additions|
- - -
In the documentation, the current summary says:
"Write variable to a text file"
This makes no mention of the fact that Write can be used to write to standard output.
A suggested change to this would be
"Write variable to a text file or standard output"
- - -
The current documentation does not mention that Write causes an exception on Windows when no file is open on GUI apps. Maybe this should be another 'Remark:'?
|Additional Information||I believe implementing the changes mentioned will help clarify the documentation for newer users who may be puzzled by Write's failure on Windows GUI apps, as well as clearly acknowledging that Write actually can be used to write to standard output when no file is open.|
|Tags||No tags attached.|
|Fixed in Revision||1734|
||Weel, stdout is a text file ...|
> Weel, stdout is a text file ...
Perhaps, but if you're new to Free Pascal and need to know the Free Pascal version of print, printf or std::cout, you're going to look in the documentation for something like 'standard output' or 'stdout'. 'text file' doesn't seem like a synonym of 'standard output'.
Same discussion as in https://wiki.freepascal.org/Special:PermanentLink/136793#questionable_claims
I don’t think it’s our task to cater specifically to the C programmer, the procedure summary is perfectly legitimate, concise, and complete.
> the procedure summary is perfectly legitimate, concise, and complete.
I disagree, but I appear to be in the minority.
I've always thought it best to help developers of any language find the information they need quickly, without needing a 'secret handshake' or getting harassed on forums. Tradition isn't always best -- sometimes rethinking things to better your users is a step in the right direction.
> I don’t think it’s our task to cater specifically to the C programmer
It was not my intention to single out just C/C++ programmers. Do you want Free Pascal users to succeed, no matter which language they came from, or do you want them to get frustrated and go elsewhere? What's the point of documentation if it's not going to be clear and informative for users -- especially users from other languages? I would think the Free Pascal team would want it to be as pain-free as possible to get new developers up and going fast.
||Added standard output to summary and added remark about windows GUI apps.|
||Thank you :-)|
|2020-09-02 20:55||Will B||New Issue|
|2020-09-02 20:55||Will B||Status||new => assigned|
|2020-09-02 20:55||Will B||Assigned To||=> Michael Van Canneyt|
|2020-09-02 20:55||Will B||Issue generated from: 0037691|
|2020-09-02 21:13||Bart Broersma||Note Added: 0125302|
|2020-09-02 21:25||Will B||Note Added: 0125303|
|2020-09-02 21:56||Kai Burghardt||Note Added: 0125305|
|2020-09-02 22:04||Will B||Note Added: 0125306|
|2020-09-02 22:09||Will B||Note Added: 0125307|
|2020-09-02 22:28||Will B||Note Edited: 0125306||View Revisions|
|2020-09-02 23:26||Michael Van Canneyt||Status||assigned => resolved|
|2020-09-02 23:26||Michael Van Canneyt||Resolution||open => fixed|
|2020-09-02 23:26||Michael Van Canneyt||Fixed in Version||=> 3.3.1|
|2020-09-02 23:26||Michael Van Canneyt||Fixed in Revision||=> 1734|
|2020-09-02 23:26||Michael Van Canneyt||FPCTarget||=> 3.2.2|
|2020-09-02 23:26||Michael Van Canneyt||Note Added: 0125314|
|2020-09-02 23:27||Michael Van Canneyt||Relationship added||related to 0037691|
|2020-09-02 23:56||Will B||Note Added: 0125319|