Re: 02/04: doc: Update README to refer to the manual.
Ludovic Courtès writes: Hi Ludo! > Jan Nieuwenhuizen skribis: > >>> commit c75a80189fc19f6ff8b4c82d1d1801be6763b6d2 >>> Author: Ludovic Courtès >>> 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 | GNU LilyPond http://lilypond.org Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com
Re: 02/04: doc: Update README to refer to the manual.
Hello! :-) Jan Nieuwenhuizen skribis: >> commit c75a80189fc19f6ff8b4c82d1d1801be6763b6d2 >> Author: Ludovic Courtès >> 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’.
Re: 02/04: doc: Update README to refer to the manual.
Hi! > commit c75a80189fc19f6ff8b4c82d1d1801be6763b6d2 > Author: Ludovic Courtès > 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 | GNU LilyPond http://lilypond.org Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com
