* Re: timestamp
2022-02-12 11:49 ` timestamp Ricardo Wurmus
@ 2022-02-12 12:32 ` tomas
2022-02-12 12:38 ` timestamp Eli Zaretskii
2022-02-12 13:30 ` timestamp adriano
2 siblings, 0 replies; 22+ messages in thread
From: tomas @ 2022-02-12 12:32 UTC (permalink / raw)
To: Ricardo Wurmus; +Cc: guile-user
[-- Attachment #1: Type: text/plain, Size: 2244 bytes --]
On Sat, Feb 12, 2022 at 12:49:10PM +0100, Ricardo Wurmus wrote:
>
> Hi adriano,
>
> I’ve got no good answers as to “why” things are the way they are, but
> the manual explains the range of these values:
>
> > It seesm to be
> >
> > (tm:mon %3)
> >
> > This returns
> >
> > 11
> >
> > I expected 12 but ok, I recognize this kind of weirdness
>
> -- Scheme Procedure: tm:mon tm
> -- Scheme Procedure: set-tm:mon tm val
> Month (0-11).
>
> > I'm unhappy with
> >
> > (tm:year $3)
> >
> > This returns
> >
> > 120
> >
> > it's 2020
> >
> > Why would 120 represent 2020 ?
>
> -- Scheme Procedure: tm:year tm
> -- Scheme Procedure: set-tm:year tm val
> Year (70-), the year minus 1900.
>
> I don’t know why this would be useful, but that’s what it is ¯\_(ツ)_/¯
Oh. That is old POSIXy tradition :-)
Guile actually only passes along what libc provides, and I think it is a
good idea, in general. See the man page of localtime(3) on your next Linux-ish
box for all the details. If you prefer an online version, perhaps [1], [2]
convey an idea.
The year... those interfaces were developed well before the year 2000. It was
usual, Back Then (TM) to write down the year as a two-digit number (the 19
prefix was implied). Nobody could predict that the year 2000 was about to
arrive, honestly ;-)
As to the month... zero based numberings ease computations and setting up
name arrays (as in: 0: January, 1: February and so on).
Don't ask me why, though, the day of the month (1..31) is one-based. It is
the only exception :-)
But it makes for an easy calculation where you can add up the year (times
year length, taking leap years into account), the days-in-month so far for
full months and the current month day and things to arrive at the current
Epoch day. Guess one has to be one-based, otherwise you'll have to add 1 at
the end.
(This is all somewhat tongue-in-cheek ;-P
But it illustrates some other point: for folks coming from C and POSIX, (I
do), all that stuff feels "pretty natural", although it isn't, of course.
Cheers
[1] https://en.cppreference.com/w/c/chrono/localtime
[2] https://en.cppreference.com/w/c/chrono/tm
--
t
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: timestamp
2022-02-12 11:49 ` timestamp Ricardo Wurmus
2022-02-12 12:32 ` timestamp tomas
@ 2022-02-12 12:38 ` Eli Zaretskii
2022-02-12 13:30 ` timestamp adriano
2 siblings, 0 replies; 22+ messages in thread
From: Eli Zaretskii @ 2022-02-12 12:38 UTC (permalink / raw)
To: Ricardo Wurmus; +Cc: guile-user
> From: Ricardo Wurmus <rekado@elephly.net>
> Date: Sat, 12 Feb 2022 12:49:10 +0100
> Cc: guile-user@gnu.org
>
>
> Hi adriano,
>
> I’ve got no good answers as to “why” things are the way they are, but
> the manual explains the range of these values:
>
> > It seesm to be
> >
> > (tm:mon %3)
> >
> > This returns
> >
> > 11
> >
> > I expected 12 but ok, I recognize this kind of weirdness
>
> -- Scheme Procedure: tm:mon tm
> -- Scheme Procedure: set-tm:mon tm val
> Month (0-11).
>
> > I'm unhappy with
> >
> > (tm:year $3)
> >
> > This returns
> >
> > 120
> >
> > it's 2020
> >
> > Why would 120 represent 2020 ?
>
> -- Scheme Procedure: tm:year tm
> -- Scheme Procedure: set-tm:year tm val
> Year (70-), the year minus 1900.
>
> I don’t know why this would be useful, but that’s what it is ¯\_(ツ)_/¯
It is simply how the C function 'localtime' returns its data,
basically for historical reasons. Guile hands it to the application
without any changes.
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: timestamp
2022-02-12 11:49 ` timestamp Ricardo Wurmus
2022-02-12 12:32 ` timestamp tomas
2022-02-12 12:38 ` timestamp Eli Zaretskii
@ 2022-02-12 13:30 ` adriano
2022-02-12 13:42 ` timestamp adriano
2022-02-12 13:49 ` timestamp Ricardo Wurmus
2 siblings, 2 replies; 22+ messages in thread
From: adriano @ 2022-02-12 13:30 UTC (permalink / raw)
To: Ricardo Wurmus; +Cc: guile-user
Hi Ricardo,
thank you for chiming in :-)
Il giorno sab, 12/02/2022 alle 12.49 +0100, Ricardo Wurmus ha scritto:
>
> Hi adriano,
>
> I’ve got no good answers as to “why” things are the way they are, but
> the manual explains the range of these values:
You're right, the manual does explain the range of these values, so the
experience can be less punishng than I perceive it to be
I had just overlooked those bits, I was't readng hard enough, actually
I think there's a reason for that but I need to digress a bit
My main gripe with the Manual is its "reference" nature
I'd love it to consider the experience of wanting to cover a use case
as the starting point of exposition
Instead it considers features as starting points and it leaves to work
to stitch together a solution for their use case to the reader
It's a matter of cognitive styles, there's no universal solution
A manual centered on use cases would baffle _some_ people
The argument of lack of examples in the Guile/Guix documentation has
been made several times now, or at least, I've seen it being made
several times
Although there's no solution in sight, this reaasures me to some extent
Because it means that the community is not completely blind in respect
to this issue
As for me, I like to mention that I had individuated this talk at the
Fosdem 2017
https://archive.fosdem.org/2017/schedule/event/legacy_docs/
and I proposed an excerpt from that talk in my videos about how to read
a file in Guile (a basic use case and its solution)
But today I'd like to also mention something else
It's a project called "bropages"
It's meant to be used like the "man pages" tool but it's made only by
example
Quick dry examples
Do you see a pattern here ? :-)
http://bropages.org/
Admittedly the name of this project is a bit unfortunate, but that's a
different argument ;-)
ok, I digressed enough
The reason why I overlooked those bits is that I get frustrated when I
land in manual pages that repost long lists of procedure I'm not sure
what to do with, unless I think of that a bit
So I skim, I jump around in the page, trying to minimize frustration
This morning I'm playing with a use case of mine
These days I'm training in a gym and I have an agreement with a
personal trainer
I shoot myself while training, I send them the footages on whatsapp
(sigh) and they send me back some more footages in which they
comment/correct my execution
So I have a folder with a bunch of files named like this
VID-20220129-WA0021
VID-20220202-WA0019
VID-20220207-WA0025
...
I'm mumbling of a script that can group these files by day
meaning putting in a subfolder all the files having the same date in
their name
maybe such subfolder could have an expressive name
so I would have a collection of days/subfolders
The bunch of files I have now is quite hard to parse
I hope I was clear
So today i read about the stat* procedures, I moved from "stat:perms"
to "access?"
So, ok, now I know how to check a file
I also read about datetimes and converting from/to epochs
So now, if I can find the way to access the _name_ of a file, I could
isolate the substring expressing the date and parse it to get an epoch
Then I could start to think about how to group files by date
(in Clojure there's a library procedure that groups dictionaries by key
but that's an argument for a different thread)
So, in laying the logical stones in my script/wall, I have to go
through the manual over and over again to fish for useful bits and
stitch together my subpatterns made of small stones
Ten I'll have to assemble my subpatterns...
This kind of process is frustrating to me
Rather than stitching together features to build solutions to use
cases, I'd prefer so much to sew together new use cases starting form
preexisting one (as the bropages dudes seem to like)
Again, this is a subjective preference, there's no obvious solution
I'd refrain from arguing that the Guile manual authors were not smart
enough because their documentation is pointlessly selective, I
understand that this was done in good faith
I'd rather contend that people with this specific cognitive style are
smart and people with a different style are less smart but again this
is another argument
I'd love if people would refrain from arguing that having a hard time
with Guile documentation means you're not tryng hard enough or that
you're not smart enough
Again, I understand that this argument isn't necessarily made
maliciously
But between Guile curse of knowledge and this kind of arguments, I
believe this explain quite a bit the difference in success between
Guile and Python or Javascript
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: timestamp
2022-02-12 13:30 ` timestamp adriano
@ 2022-02-12 13:42 ` adriano
2022-02-12 13:49 ` timestamp Ricardo Wurmus
1 sibling, 0 replies; 22+ messages in thread
From: adriano @ 2022-02-12 13:42 UTC (permalink / raw)
To: Ricardo Wurmus; +Cc: guile-user
I brought up these arguments up today because the recent discussions
about Guile/Guix documentation encouraged me
Those make me feel that not all is lost :-)
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: timestamp
2022-02-12 13:30 ` timestamp adriano
2022-02-12 13:42 ` timestamp adriano
@ 2022-02-12 13:49 ` Ricardo Wurmus
2022-02-12 13:55 ` timestamp adriano
2022-02-12 17:32 ` timestamp Eli Zaretskii
1 sibling, 2 replies; 22+ messages in thread
From: Ricardo Wurmus @ 2022-02-12 13:49 UTC (permalink / raw)
To: adriano; +Cc: guile-user
adriano <randomlooser@riseup.net> writes:
> The argument of lack of examples in the Guile/Guix documentation has
> been made several times now, or at least, I've seen it being made
> several times
The Guix documentation contains examples, but it’s already very long and
intimidating, so we started the Cookbook for more extensive tutorials
and examples.
It hasn’t seen as much uptake by contributors as I hoped, but it’s there
and can be extended with more examples, big and small.
--
Ricardo
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: timestamp
2022-02-12 13:49 ` timestamp Ricardo Wurmus
@ 2022-02-12 13:55 ` adriano
2022-02-12 14:01 ` Guile cookbook ? adriano
2022-02-12 17:32 ` timestamp Eli Zaretskii
1 sibling, 1 reply; 22+ messages in thread
From: adriano @ 2022-02-12 13:55 UTC (permalink / raw)
To: Ricardo Wurmus; +Cc: guile-user
Il giorno sab, 12/02/2022 alle 14.49 +0100, Ricardo Wurmus ha scritto:
>
> adriano <randomlooser@riseup.net> writes:
>
> > The argument of lack of examples in the Guile/Guix documentation
> > has
> > been made several times now, or at least, I've seen it being made
> > several times
>
> The Guix documentation contains examples, but it’s already very long
> and
> intimidating, so we started the Cookbook for more extensive tutorials
> and examples.
>
> It hasn’t seen as much uptake by contributors as I hoped, but it’s
> there
> and can be extended with more examples, big and small.
>
Hint taken :-)
^ permalink raw reply [flat|nested] 22+ messages in thread
* Guile cookbook ?
2022-02-12 13:55 ` timestamp adriano
@ 2022-02-12 14:01 ` adriano
2022-02-12 14:15 ` Ricardo Wurmus
` (2 more replies)
0 siblings, 3 replies; 22+ messages in thread
From: adriano @ 2022-02-12 14:01 UTC (permalink / raw)
To: Ricardo Wurmus; +Cc: guile-user
Il giorno sab, 12/02/2022 alle 14.55 +0100, adriano ha scritto:
>
> Hint taken :-)
Actually, I was thinking about a Guile cookbook, rather than the Guix
cookbook
Can the Guix cookbook also contain examples of how o do things in Guile
?
Even things that are no related to Guix ?
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: Guile cookbook ?
2022-02-12 14:01 ` Guile cookbook ? adriano
@ 2022-02-12 14:15 ` Ricardo Wurmus
2022-02-12 15:01 ` adriano
2022-02-12 15:30 ` Olivier Dion via General Guile related discussions
2022-02-12 17:11 ` Zelphir Kaltstahl
2 siblings, 1 reply; 22+ messages in thread
From: Ricardo Wurmus @ 2022-02-12 14:15 UTC (permalink / raw)
To: adriano; +Cc: guile-user
adriano <randomlooser@riseup.net> writes:
> Il giorno sab, 12/02/2022 alle 14.55 +0100, adriano ha scritto:
>>
>
>> Hint taken :-)
>
> Actually, I was thinking about a Guile cookbook, rather than the Guix
> cookbook
>
> Can the Guix cookbook also contain examples of how o do things in Guile
> ?
>
> Even things that are no related to Guix ?
It already contains a couple of Guile-only things (like the Scheme
tutorial), but I mentioned it only because you talked about examples in
the Guix manual.
Perhaps the Guile manual would benefit from an accompanying cookbook
with tutorials, examples, common problems, etc?
--
Ricardo
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: Guile cookbook ?
2022-02-12 14:15 ` Ricardo Wurmus
@ 2022-02-12 15:01 ` adriano
0 siblings, 0 replies; 22+ messages in thread
From: adriano @ 2022-02-12 15:01 UTC (permalink / raw)
To: Ricardo Wurmus; +Cc: guile-user
Il giorno sab, 12/02/2022 alle 15.15 +0100, Ricardo Wurmus ha scritto:
>
> adriano <randomlooser@riseup.net> writes:
>
> > Il giorno sab, 12/02/2022 alle 14.55 +0100, adriano ha scritto:
> > >
> >
> > > Hint taken :-)
> >
> > Actually, I was thinking about a Guile cookbook, rather than the
> > Guix
> > cookbook
> >
> > Can the Guix cookbook also contain examples of how o do things in
> > Guile
> > ?
> >
> > Even things that are no related to Guix ?
>
> It already contains a couple of Guile-only things (like the Scheme
> tutorial), but I mentioned it only because you talked about examples
> in
> the Guix manual.
>
> Perhaps the Guile manual would benefit from an accompanying cookbook
> with tutorials, examples, common problems, etc?
>
I'd be glad to contribute to such a cookbook
The example of how to read a file is ready, it requires no research
It's a very basic use case but also a very common one
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: Guile cookbook ?
2022-02-12 14:01 ` Guile cookbook ? adriano
2022-02-12 14:15 ` Ricardo Wurmus
@ 2022-02-12 15:30 ` Olivier Dion via General Guile related discussions
2022-02-12 17:11 ` Zelphir Kaltstahl
2 siblings, 0 replies; 22+ messages in thread
From: Olivier Dion via General Guile related discussions @ 2022-02-12 15:30 UTC (permalink / raw)
To: adriano, Ricardo Wurmus; +Cc: guile-user
On Sat, 12 Feb 2022, adriano <randomlooser@riseup.net> wrote:
> Il giorno sab, 12/02/2022 alle 14.55 +0100, adriano ha scritto:
>>
>
>> Hint taken :-)
>
> Actually, I was thinking about a Guile cookbook, rather than the Guix
> cookbook
>
> Can the Guix cookbook also contain examples of how o do things in Guile
> ?
>
> Even things that are no related to Guix ?
I think it would be best to kept them apart. A Guile cookbook is
definitively a good idea. It would be very trivial to start this as a
org-mode file and share it on a public repo, possibly adding a link to
the main website if it gets momentum.
--
Olivier Dion
Polymtl
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: Guile cookbook ?
2022-02-12 14:01 ` Guile cookbook ? adriano
2022-02-12 14:15 ` Ricardo Wurmus
2022-02-12 15:30 ` Olivier Dion via General Guile related discussions
@ 2022-02-12 17:11 ` Zelphir Kaltstahl
2 siblings, 0 replies; 22+ messages in thread
From: Zelphir Kaltstahl @ 2022-02-12 17:11 UTC (permalink / raw)
To: guile-user
On 2/12/22 15:01, adriano wrote:
> Il giorno sab, 12/02/2022 alle 14.55 +0100, adriano ha scritto:
>> Hint taken :-)
> Actually, I was thinking about a Guile cookbook, rather than the Guix
> cookbook
>
> Can the Guix cookbook also contain examples of how o do things in Guile
> ?
>
> Even things that are no related to Guix ?
Hi Adriano and everyone,
some more time examples:https://notabug.org/ZelphirKaltstahl/guile-examples/src/master/time Perhaps they can help.
If there is going to be a cookbook, feel free to copy examples and so on.
Best regards,
Zelphir
--
repositories: https://notabug.org/ZelphirKaltstahl
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: timestamp
2022-02-12 13:49 ` timestamp Ricardo Wurmus
2022-02-12 13:55 ` timestamp adriano
@ 2022-02-12 17:32 ` Eli Zaretskii
2022-02-12 17:48 ` Examples in Guile documentation Zelphir Kaltstahl
1 sibling, 1 reply; 22+ messages in thread
From: Eli Zaretskii @ 2022-02-12 17:32 UTC (permalink / raw)
To: Ricardo Wurmus; +Cc: guile-user
> From: Ricardo Wurmus <rekado@elephly.net>
> Date: Sat, 12 Feb 2022 14:49:20 +0100
> Cc: guile-user@gnu.org
>
> > The argument of lack of examples in the Guile/Guix documentation has
> > been made several times now, or at least, I've seen it being made
> > several times
>
> The Guix documentation contains examples, but it’s already very long and
> intimidating, so we started the Cookbook for more extensive tutorials
> and examples.
>
> It hasn’t seen as much uptake by contributors as I hoped, but it’s there
> and can be extended with more examples, big and small.
I don't think just adding examples will cut it, although it will
certainly help.
My take of the issue is that the Guile reference manual is little more
than the collection of the doc strings of the various Guile APIs. The
doc strings are by their very nature quite terse and lack the "glue":
the text which will explain the relative merits and demerits of each
API wrt the other, the factors to consider when deciding which APIs to
use, etc. It also doesn't make it easy to have helpful
cross-references. Moreover, adding examples to the doc strings will
have a disadvantage: it will increase the memory footprint of running
Guile applications.
Which is why I think the effort should be in the direction of
extending the parts of the manual that aren't produced from the doc
strings, but instead are written by humans to help other humans.
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: Examples in Guile documentation
2022-02-12 17:32 ` timestamp Eli Zaretskii
@ 2022-02-12 17:48 ` Zelphir Kaltstahl
0 siblings, 0 replies; 22+ messages in thread
From: Zelphir Kaltstahl @ 2022-02-12 17:48 UTC (permalink / raw)
To: guile-user
On 2/12/22 18:32, Eli Zaretskii wrote:
>> From: Ricardo Wurmus <rekado@elephly.net>
>> Date: Sat, 12 Feb 2022 14:49:20 +0100
>> Cc: guile-user@gnu.org
>>
>>> The argument of lack of examples in the Guile/Guix documentation has
>>> been made several times now, or at least, I've seen it being made
>>> several times
>> The Guix documentation contains examples, but it’s already very long and
>> intimidating, so we started the Cookbook for more extensive tutorials
>> and examples.
>>
>> It hasn’t seen as much uptake by contributors as I hoped, but it’s there
>> and can be extended with more examples, big and small.
> I don't think just adding examples will cut it, although it will
> certainly help.
Only adding examples might not be enough, but definitely a huge step forward. In
whatever form they appear, a separate Cookbook, or whatever. The number of
times, I have sat in front of the reference manual and needed to try things out,
in order to figure out how to make use of something in the manual is high.
Examples would surely be a very beginner friendly thing to do.
> My take of the issue is that the Guile reference manual is little more
> than the collection of the doc strings of the various Guile APIs. The
> doc strings are by their very nature quite terse and lack the "glue":
> the text which will explain the relative merits and demerits of each
> API wrt the other, the factors to consider when deciding which APIs to
> use, etc. It also doesn't make it easy to have helpful
> cross-references. Moreover, adding examples to the doc strings will
> have a disadvantage: it will increase the memory footprint of running
> Guile applications.
>
> Which is why I think the effort should be in the direction of
> extending the parts of the manual that aren't produced from the doc
> strings, but instead are written by humans to help other humans.
Best regards,
Zelphir
--
repositories: https://notabug.org/ZelphirKaltstahl
^ permalink raw reply [flat|nested] 22+ messages in thread