[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation
|
From: |
Mohammad-Reza Nabipoor |
|
Subject: |
Re: Documentation |
|
Date: |
Tue, 15 Sep 2020 20:32:27 +0430 |
Hi Jose
Thanks for your feedbacks, I'll update it ASAP.
But before that I have a bunch questions and comments.
On Tue, Sep 15, 2020 at 11:38:01AM +0200, Jose E. Marchesi wrote:
I think you are too optimistic regarding the current state of the
manual... or maybe I'm being too pesimist! I really wish someone would
help us with that.
I'll try improve it (despite the fact that I'm not that knowledgeable about
GNU poke and also I'm not good at writing).
BTW do you know why the index page of HTML documentation is empty?
It looks like a bug. This is what I get as the last lines of `index.html`:
```html
<body lang="en">
<span id="SEC_Contents"></span>
```
/* First start with nomenclature:
*
* - poke The editor program (also called GNU poke)
* - Poke Domain-specific programming language that used by `poke`
* - pickle A Poke source file. The extension of filename is `.pk`
A pickle is not any Poke source file: it is a Poke source file that
implements some definited domain, like a file format (like ELF) or some
functional domain (like time.pk). You may want to reflect that in the
summary..
So a pickle is a set of related stuff (types, functions, units, ...).
That reminds me of the definition of modules! Is this a correct interpretation?
(I know that in future we'll have modules in Poke)
/* Array trimming: Extraction of a subset of the array */
defvar arr3 = arr1[0:1]; /* arr3 == [1, 2] */
Probably it is worth mentioning that the provided indexes in a trim are
both inclusive.
OK.
And a comment about this feature: I really don't like this feature (using closed
ranges (intervals) instead of half-open ranges). IMHO dealing with half-open
ranges are much more simpler.
I guess you've made this decision because of Algol68 :D
Today I moved ptime and the POSIX_Time{32,64} definitions to a pickle
pickles/time.pk.
std.pk should only be used to define "standard" language constructions,
such as the standard basic types. The "standard library" of Poke is in
reality std.pk + pickles/*.pk.
... I guess :)
Before this I treated `pickles/*.pk` files as a bunch of examples :D
Now I know that those are part of "standard library"!
Thanks for the clarification.
So should I change this title "std.pk - Standard definition for poke"?
Or just removing the DateTime stuff is enough?
And what do you think about adding one-line description for each of pickles in
`pickles` directory?
* - Auto-growing memory buffer
* - Address-space of a process
Not yet. Someone should write a ptrace-based IOD :)
Should I remove this line?
Or just add a comment that this is not available yet?
/* To access to IO space we can map a value to some area using this syntax:
*
* TYPE @ OFFST
* or,
* TYPE @ IOS : OFFSET
*/
defvar ui32num = uint<32> @ 0#B;
defvar i32num = int<32> @ 4#B;
/* If we modify the `ui32num` the first 4 bytes in IO space will change. */
ui32num = 0xaabbccdd;
Not really. `ui32num' is a simple value (integer, offset, string) and
therefore it is not mapped:
ui32num'mapped -> 0
In order to perform the operation above you would need to do something
like:
uint<32> @ 0#B = 0xaabbccdd;
Interesting!
Can I say that there are two kinds of types in Poke?
- Types with value semantics (like integers, offsets, strings and array of
them)
- Types with reference semantics (like structs, unions and array of them)
So when we define a variable of a type with value semantics the value will
be copied, and when we have a variable of a type with reference semantics, the
"address" will be copied and we can modify the source.
Or should I call them "simple values" and "non-simple values"?
WDYT?
Very very nice work... once it is more complete we should include it not
only on the website, but also in the manual!
Thank you.
Thanks! That's very good. I'll try my best to make it happen :)
Regards,
Mohammad-Reza