unofficial mirror of guix-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Re: 02/04: doc: Update README to refer to the manual.
       [not found] ` <20200602170006.4CE5220A26@vcs0.savannah.gnu.org>
@ 2020-06-03  9:23   ` Jan Nieuwenhuizen
  2020-06-04 12:24     ` Ludovic Courtès
  0 siblings, 1 reply; 3+ messages in thread
From: Jan Nieuwenhuizen @ 2020-06-03  9:23 UTC (permalink / raw)
  To: Ludovic Courtès ; +Cc: guix-devel


Hi!

> commit c75a80189fc19f6ff8b4c82d1d1801be6763b6d2
> Author: Ludovic Courtès <ludo@gnu.org>
> AuthorDate: Tue Jun 2 14:50:54 2020 +0200
>
>     doc: Update README to refer to the manual.
>
>     * README (Requirements): Refer to the manual.
>     (Installation): Update URL of the manual.

Hmm, I don't like it!  Also, no rationale.

> +If you are building Guix from source, please see the manual for build
> +instructions and requirements, either by running:
>  
> -  - [[https://gnu.org/software/guile/][GNU Guile 2.2.x]]
> -  - [[https://notabug.org/cwebber/guile-gcrypt][Guile-Gcrypt]] 0.1.0 or later
> -  - [[https://www.gnu.org/software/make/][GNU Make]]
> -  - [[https://www.gnutls.org][GnuTLS]] compiled with guile support enabled
> -  - [[https://notabug.org/guile-sqlite3/guile-sqlite3][Guile-SQLite3]], version 0.1.0 or later
> -  - [[https://gitlab.com/guile-git/guile-git][Guile-Git]]
> -  - [[http://www.zlib.net/][zlib]]
> -  - [[https://savannah.nongnu.org/projects/guile-json/][Guile-JSON]]
> +  info -f doc/guix.info "Requirements"

I can guess how the information in README is a duplication of what we have
in the maunual, and possibly even (somewhat) out of date, so for us as
developers/maintainers this means extra work...

> +or by checking the [[https://guix.gnu.org/manual/en/html_node/Installation.html][web copy of the manual]].
>  
>  For information on installation from a Git checkout, please see the section
>  "Building from Git" in the manual.

...but as a new potential user of a software I have often cursed the
makers for providing "empty" READMEs that refer to documentation that is
neither built (yet) or shipped, or needs a viewer/web browser; making it
most convenient for them, the writers, and not for me, the reader;
leaving me puzzled ... "So, you'd rather not have me use your software?"

I'm wondering if you haven't had that experience, and how you look at
this...

As an aside: what has always puzzled me is that GNU has failed/not
bothered yet to come up with some sort of standard file to list a
package's dependencies.  If you're lucky, it's available in human
readable form README, or INSTALL, or ...

Sorry to be so grumpy ;)

Greetings,
Janneke

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


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

* Re: 02/04: doc: Update README to refer to the manual.
  2020-06-03  9:23   ` 02/04: doc: Update README to refer to the manual Jan Nieuwenhuizen
@ 2020-06-04 12:24     ` Ludovic Courtès
  2020-06-04 19:30       ` Jan Nieuwenhuizen
  0 siblings, 1 reply; 3+ messages in thread
From: Ludovic Courtès @ 2020-06-04 12:24 UTC (permalink / raw)
  To: Jan Nieuwenhuizen; +Cc: guix-devel

Hello!  :-)

Jan Nieuwenhuizen <janneke@gnu.org> skribis:

>> commit c75a80189fc19f6ff8b4c82d1d1801be6763b6d2
>> Author: Ludovic Courtès <ludo@gnu.org>
>> AuthorDate: Tue Jun 2 14:50:54 2020 +0200
>>
>>     doc: Update README to refer to the manual.
>>
>>     * README (Requirements): Refer to the manual.
>>     (Installation): Update URL of the manual.
>
> Hmm, I don't like it!  Also, no rationale.

Someone reported that the list of dependencies (the Guile version in
particular) in ‘README’ was outdated.  I set out to update it and then
realized that that info was already available and up-to-date in the
manual.  Hence this patch.

>> +or by checking the [[https://guix.gnu.org/manual/en/html_node/Installation.html][web copy of the manual]].
>>  
>>  For information on installation from a Git checkout, please see the section
>>  "Building from Git" in the manual.
>
> ...but as a new potential user of a software I have often cursed the
> makers for providing "empty" READMEs that refer to documentation that is
> neither built (yet) or shipped, or needs a viewer/web browser; making it
> most convenient for them, the writers, and not for me, the reader;
> leaving me puzzled ... "So, you'd rather not have me use your software?"
>
> I'm wondering if you haven't had that experience, and how you look at
> this...

Sure.  Two things:

  1. People installing a release from a tarball have doc/guix.info
     already built.

  2. The ‘README’ also gives the URL of the on-line copy of the manual.

So I think the information is readily available.

My goal here was just to avoid having an outdated copy of parts of the
manual.

I hope that makes sense!

Ludo’.


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

* Re: 02/04: doc: Update README to refer to the manual.
  2020-06-04 12:24     ` Ludovic Courtès
@ 2020-06-04 19:30       ` Jan Nieuwenhuizen
  0 siblings, 0 replies; 3+ messages in thread
From: Jan Nieuwenhuizen @ 2020-06-04 19:30 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

Ludovic Courtès writes:

Hi Ludo!

> Jan Nieuwenhuizen <janneke@gnu.org> skribis:
>
>>> commit c75a80189fc19f6ff8b4c82d1d1801be6763b6d2
>>> Author: Ludovic Courtès <ludo@gnu.org>
>>> AuthorDate: Tue Jun 2 14:50:54 2020 +0200
>>>
>>>     doc: Update README to refer to the manual.
>>>
>>>     * README (Requirements): Refer to the manual.
>>>     (Installation): Update URL of the manual.
>>
>> Hmm, I don't like it!  Also, no rationale.
>
> Someone reported that the list of dependencies (the Guile version in
> particular) in ‘README’ was outdated.  I set out to update it and then
> realized that that info was already available and up-to-date in the
> manual.  Hence this patch.

Okay...

>> ...but as a new potential user of a software I have often cursed the
>> makers for providing "empty" READMEs that refer to documentation that is
>> neither built (yet) or shipped, or needs a viewer/web browser; making it
>> most convenient for them, the writers, and not for me, the reader;
>> leaving me puzzled ... "So, you'd rather not have me use your software?"
>>
>> I'm wondering if you haven't had that experience, and how you look at
>> this...
>
> Sure.  Two things:
>
>   1. People installing a release from a tarball have doc/guix.info
>      already built.

Ah, that's right.

>   2. The ‘README’ also gives the URL of the on-line copy of the manual.
>
> So I think the information is readily available.
>
> My goal here was just to avoid having an outdated copy of parts of the
> manual.
>
> I hope that makes sense!

Yes...it looks like this struck a nerve; I'll think about it.

Thanks; Greetings,
Janneke

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


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

end of thread, other threads:[~2020-06-04 19:30 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
     [not found] <20200602170004.20721.34450@vcs0.savannah.gnu.org>
     [not found] ` <20200602170006.4CE5220A26@vcs0.savannah.gnu.org>
2020-06-03  9:23   ` 02/04: doc: Update README to refer to the manual Jan Nieuwenhuizen
2020-06-04 12:24     ` Ludovic Courtès
2020-06-04 19:30       ` Jan Nieuwenhuizen

Code repositories for project(s) associated with this public inbox

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

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).