Re: [TCLCORE] Documentation of the documentation command for 9.0

[Harald O. <har...@el...>]

Am 14.06.2024 um 20:21 schrieb Poor Yorick:
> On 2024-06-14 18:25, Harald Oehlmann wrote:
>> Dear TCL team,
>>
>> the encoding command was revised with TCL 9.
>>
>> Many people contributed to this page. A rewrite is proposed by Nathan 
>> in the branch "encoding-for-review":
>>
>> https://core.tcl-lang.org/tcl/info/4d6aa33b2f
>>
>> Inspired from this change, a new version is proposed in the branch 
>> "encoding-for-review-alt":
>>
>> https://core.tcl-lang.org/tcl/info/f5243d7263ce854a
>>
> 
> The following excerpt is from the encoding-for-review-alt branch:
> 
> 
>      "Strings in a certain encoding are represented within Tcl as binary 
> data
>      and may not be handled as Tcl strings any more."
> 
> One of the main points of my original rewrite was to ensure that the reader
> understands that every value really is a string, including all values that
> represent "binary" data. Sentences like the one above are very 
> misleading to
> the newcomer trying to understand how to work with binary data in a 
> language
> where everything is a string.  It's also just straight-up incorrect. It's
> important to carefully articulate throughout the documentation that 
> there is no
> magical "binary" mode, and that every "binary" value really is just a 
> normal
> Unicode string.  Therefore the sentence above and all sentences like it 
> should
> be removed.
> 
> Also, documentation is uses singular case as much as possible is generally
> easier to read.  One technique to achieve this is to use the word "each" 
> and
> "every" in place of using other words in the plural case.
> 

Dear Nathan,
thanks, great. Yes, I feel it really difficult to make people understand 
what really happens. I tried to reword the "binary string" part.
What do you think now?

About "every" or "one" and "easier to read". That is an opinion, thanks 
for that.

Take care,
Harald