all messages for Guix-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* extending the documentation of the Scheme API
@ 2019-12-20 22:17 Ricardo Wurmus
  2019-12-21  1:45 ` John Soo
                   ` (3 more replies)
  0 siblings, 4 replies; 7+ messages in thread
From: Ricardo Wurmus @ 2019-12-20 22:17 UTC (permalink / raw)
  To: Guix-devel

Hi Guix,

we have lots of nice macros and procedures in Guix that aren’t
documented beyond their docstrings.

Should we snarf the docstrings and add them to the manual?

--
Ricardo

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: extending the documentation of the Scheme API
  2019-12-20 22:17 extending the documentation of the Scheme API Ricardo Wurmus
@ 2019-12-21  1:45 ` John Soo
  2019-12-21  4:04 ` Jesse Gibbons
                   ` (2 subsequent siblings)
  3 siblings, 0 replies; 7+ messages in thread
From: John Soo @ 2019-12-21  1:45 UTC (permalink / raw)
  To: Ricardo Wurmus; +Cc: Guix-devel

Hi Ricardo,

Yes! I think that would really emphasize the hackability of Guix. 

- John

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: extending the documentation of the Scheme API
  2019-12-20 22:17 extending the documentation of the Scheme API Ricardo Wurmus
  2019-12-21  1:45 ` John Soo
@ 2019-12-21  4:04 ` Jesse Gibbons
  2019-12-21 12:24   ` Pjotr Prins
  2019-12-23 11:44 ` Bengt Richter
  2019-12-29  8:20 ` Jan Nieuwenhuizen
  3 siblings, 1 reply; 7+ messages in thread
From: Jesse Gibbons @ 2019-12-21  4:04 UTC (permalink / raw)
  To: Ricardo Wurmus, Guix-devel

On Fri, 2019-12-20 at 23:17 +0100, Ricardo Wurmus wrote:
> Hi Guix,
> 
> we have lots of nice macros and procedures in Guix that aren’t
> documented beyond their docstrings.
> 
> Should we snarf the docstrings and add them to the manual?
> 
> --
> Ricardo
> 
> 
I don't care where it goes, but is there maybe a better place than the guix
manual?

Am I alone in thinking it makes sense to produce a "guix api reference
manual"? The guix manual is already fairly large. We can treat the guix
manual as a manual for setting up guix and using it from a shell, the guix
api reference manual as a reference for `guix repl` and more complex package
and service production.

This is just something I think we should consider.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: extending the documentation of the Scheme API
  2019-12-21  4:04 ` Jesse Gibbons
@ 2019-12-21 12:24   ` Pjotr Prins
  0 siblings, 0 replies; 7+ messages in thread
From: Pjotr Prins @ 2019-12-21 12:24 UTC (permalink / raw)
  To: Jesse Gibbons; +Cc: Guix-devel

On Fri, Dec 20, 2019 at 09:04:16PM -0700, Jesse Gibbons wrote:
> On Fri, 2019-12-20 at 23:17 +0100, Ricardo Wurmus wrote:
> > Hi Guix,
> > 
> > we have lots of nice macros and procedures in Guix that aren’t
> > documented beyond their docstrings.
> > 
> > Should we snarf the docstrings and add them to the manual?
> > 
> > --
> > Ricardo
> > 
> > 
> I don't care where it goes, but is there maybe a better place than the guix
> manual?
> 
> Am I alone in thinking it makes sense to produce a "guix api reference
> manual"? The guix manual is already fairly large. We can treat the guix
> manual as a manual for setting up guix and using it from a shell, the guix
> api reference manual as a reference for `guix repl` and more complex package
> and service production.
> 
> This is just something I think we should consider.

How about a Guix hackers manual? Bliss from the REPL. I think that is
one of the key assets of Guix while it is still pretty hard to get at
without documentation.

Pj.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: extending the documentation of the Scheme API
  2019-12-20 22:17 extending the documentation of the Scheme API Ricardo Wurmus
  2019-12-21  1:45 ` John Soo
  2019-12-21  4:04 ` Jesse Gibbons
@ 2019-12-23 11:44 ` Bengt Richter
  2019-12-29  8:20 ` Jan Nieuwenhuizen
  3 siblings, 0 replies; 7+ messages in thread
From: Bengt Richter @ 2019-12-23 11:44 UTC (permalink / raw)
  To: Ricardo Wurmus; +Cc: Guix-devel

Hi Ricardo, Guix

On +2019-12-20 23:17:41 +0100, Ricardo Wurmus wrote:
> Hi Guix,
> 
> we have lots of nice macros and procedures in Guix that aren’t
> documented beyond their docstrings.
> 
> Should we snarf the docstrings and add them to the manual?
> 
> --
> Ricardo
> 
> 

My 2 cents, if I may:

I would _much_ rather be able to "snarf" dynamically from the command line
to stdout or -o file using appropriate parameters and options.

Even something dead simple like
gx-apropos:
--8<---------------cut here---------------start------------->8---
#!/usr/bin/bash
guile -c '(use-modules (ice-9 session))(apropos '"\"$*\""')'
--8<---------------cut here---------------end--------------->8---

quickly gets me syntax essentials for default modules.
(I have to do another variant to get this apropos to see rnrs bytevectors
or other non-default modules). Yet another variant uses oop goops describe.

I can view a manual and search it in emacs, but even so, sometimes I'd rather
insert the result of a command line invocation from within emacs.
It only takes a few seconds to grep the whole guix git repo, a bit longer for /gnu.

Speaking of the latter, here is an alpha kludge to do approximately what
ArchLinux's pacman -Qo does (find what package a given executable belongs to).

pacman -Qo $(which pacman)
--8<---------------cut here---------------start------------->8---
/usr/bin/pacman is owned by pacman 5.2.1-1
--8<---------------cut here---------------end--------------->8---

my gx-Qo version (takes multiple args and shows pure vs not):

gx-Qo g++ as readelf emacs lsblk less weston wayland gxQo
--8<---------------cut here---------------start------------->8---
g++:	gcc-9.1.0
as:	binutils-2.32
readelf:	binutils-2.32
emacs:	emacs-26.3
lsblk:	util-linux-2.34
less:	less-530
weston:	weston-6.0.1
wayland:	(which: did not find)
gx-Qo:	(impure: '/home/bokr/bin/gx-Qo')
--8<---------------cut here---------------end--------------->8---

When I get around to it I'll add a -a option to do which -a to
report on all found. Also a -L option to report each link
(possibly a chain) leading to to the executables.

When/if I do, it will be an example of upgrading a single simple
dynamic "documentation" producer vs upgrading a document per se.

I much prefer dynamically on-the-fly-produced documentation of
the state of my system -- like /proc stuff -- it's always up to date :)
And emacs will let me escape with C-z to get to the command line
when that is convenient (or necessary if pts doesn't do some tty thing).

IMHO composing _independent_ functionalities ad-lib and powerfully
is the best gift of the bash command line.

    ...|guix hash -|...
allows me to use guix's internal default composition of sha256sum and base32,
but bash can already get at the former and IMHO it would enhance
general composability if guix's base32 were packaged as external to guix hash,
so that bash could make use of the nix encoding also, that would be a plus for me
e.g. maybe like
    ...|sha256sum|cut -d ' ' -f1|gx-base32|...

It's a matter of what options you have to compose functionality.
IMHO it would be good policy externalize hidden nuggets
of shell-composable functionality whenever the nuggets don't need
the package they come in to function.

I think this should be viewed at the system architecture level
so that the natural Chauvinism of an exciting project does not
in effect create a walled garden that prohibits[1] cloning a
simple (with simple system abi dependencies) internal wheel barrow 
for use at home.

[1]I know "prohibits" does not apply to extracting nuggets
from FOSS, but the effort can be prohibitive, where the original
developers of the nugget could have made it easy in many cases :-/

HTH in some way :)

-- 
Regards,
Bengt Richter

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: extending the documentation of the Scheme API
  2019-12-20 22:17 extending the documentation of the Scheme API Ricardo Wurmus
                   ` (2 preceding siblings ...)
  2019-12-23 11:44 ` Bengt Richter
@ 2019-12-29  8:20 ` Jan Nieuwenhuizen
  2019-12-30 18:38   ` Ludovic Courtès
  3 siblings, 1 reply; 7+ messages in thread
From: Jan Nieuwenhuizen @ 2019-12-29  8:20 UTC (permalink / raw)
  To: Ricardo Wurmus; +Cc: Guix-devel

Ricardo Wurmus writes:

Hello Ricardo

> we have lots of nice macros and procedures in Guix that aren’t
> documented beyond their docstrings.
>
> Should we snarf the docstrings and add them to the manual?

If you are talking about guix records and (guix build utils); I think it
would be great if these were split off from Guix.  I guess that
documenting them right now, as a first step, would be nice in itself.

I am not sure where Guix records could go (Guile?); but many (guix build
utils) could move to Gash or a common library even.  WDYT?

Greetings,
jannneke

-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: extending the documentation of the Scheme API
  2019-12-29  8:20 ` Jan Nieuwenhuizen
@ 2019-12-30 18:38   ` Ludovic Courtès
  0 siblings, 0 replies; 7+ messages in thread
From: Ludovic Courtès @ 2019-12-30 18:38 UTC (permalink / raw)
  To: Jan Nieuwenhuizen; +Cc: Guix-devel

Hi!

Jan Nieuwenhuizen <janneke@gnu.org> skribis:

>> we have lots of nice macros and procedures in Guix that aren’t
>> documented beyond their docstrings.
>>
>> Should we snarf the docstrings and add them to the manual?
>
> If you are talking about guix records and (guix build utils); I think it
> would be great if these were split off from Guix.  I guess that
> documenting them right now, as a first step, would be nice in itself.

It’s quite clear that the future of (guix build utils), or parts of it,
will be Gash-Core-Utils somehow.

I’m not sure about records: they’re not completely set in stone and it’s
handy to have them in the same repo, but eventually, it’ll be nicer to
have them “elsewhere.”  Same for monads.

(I like the “monorepo” approach though.  Perhaps we could have one big
Guile library repo?  :-))

In the meantime, I think documenting (guix build utils) would be helpful
to packagers.  Documenting ‘define-record-type*’ would be nice as well.

Thanks,
Ludo’.

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2019-12-30 18:38 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-12-20 22:17 extending the documentation of the Scheme API Ricardo Wurmus
2019-12-21  1:45 ` John Soo
2019-12-21  4:04 ` Jesse Gibbons
2019-12-21 12:24   ` Pjotr Prins
2019-12-23 11:44 ` Bengt Richter
2019-12-29  8:20 ` Jan Nieuwenhuizen
2019-12-30 18:38   ` Ludovic Courtès

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/guix.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.