View Issue Details

IDProjectCategoryView StatusLast Update
0037692FPCDocumentationpublic2020-09-02 23:56
ReporterWill B Assigned ToMichael Van Canneyt  
PrioritynormalSeverityminorReproducibilityN/A
Status resolvedResolutionfixed 
PlatformN/AOSN/A 
Fixed in Version3.3.1 
Summary0037692: Documentation for Write needs small additions
DescriptionSub-issue 1:
- - -
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"


Sub-issue 2:
- - -
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 InformationI 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.
TagsNo tags attached.
Fixed in Revision1734
FPCOldBugId
FPCTarget3.2.2
Attached Files

Relationships

related to 0037691 resolvedMichael Van Canneyt Documentation for WriteLn needs small additions / corrections 

Activities

Bart Broersma

2020-09-02 21:13

reporter   ~0125302

Weel, stdout is a text file ...

Will B

2020-09-02 21:25

reporter   ~0125303

> 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'.

Kai Burghardt

2020-09-02 21:56

reporter   ~0125305

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.

Will B

2020-09-02 22:04

reporter   ~0125306

Last edited: 2020-09-02 22:28

View 2 revisions

> 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.

Will B

2020-09-02 22:09

reporter   ~0125307

> 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.

Michael Van Canneyt

2020-09-02 23:26

administrator   ~0125314

Added standard output to summary and added remark about windows GUI apps.

Will B

2020-09-02 23:56

reporter   ~0125319

Thank you :-)

Issue History

Date Modified Username Field Change
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