[Top][All Lists]

[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`:

<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

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.


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

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

uint<32> @ 0#B = 0xaabbccdd;

Can I say that there are two kinds of types in Poke?
  - Types with value semantics (like integers, offsets, strings and array of 
  - 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"?


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 :)


reply via email to

[Prev in Thread] Current Thread [Next in Thread]