[PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Federico Beffa]

[-- Attachment #1: Type: text/plain, Size: 1 bytes --]



[-- Attachment #2: 0005-gnu-mit-scheme-Generate-and-install-documentation.patch --]
[-- Type: text/x-diff, Size: 5074 bytes --]

From 5c2be0d7d628ba27ac1360cc8e998de68a505b2a Mon Sep 17 00:00:00 2001
From: Federico Beffa <beffa@fbengineering.ch>
Date: Sun, 27 Dec 2015 19:06:37 +0100
Subject: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

* gnu/packages/scheme.scm (mit-scheme): Convert to the 'modify-phases'
  syntax. Add phases 'configure-doc, 'build-doc and 'install-doc. Add
  'texlive' input.
---
 gnu/packages/scheme.scm | 78 ++++++++++++++++++++++++++++++-------------------
 1 file changed, 48 insertions(+), 30 deletions(-)

diff --git a/gnu/packages/scheme.scm b/gnu/packages/scheme.scm
index 7eb03f6..f778b99 100644
--- a/gnu/packages/scheme.scm
+++ b/gnu/packages/scheme.scm
@@ -30,6 +30,7 @@
   #:use-module (gnu packages databases)
   #:use-module (gnu packages emacs)
   #:use-module (gnu packages texinfo)
+  #:use-module (gnu packages texlive)
   #:use-module (gnu packages base)
   #:use-module (gnu packages pkg-config)
   #:use-module (gnu packages avahi)
@@ -59,37 +60,54 @@
     (arguments
      `(#:tests? #f                                ; no "check" target
        #:phases
-       (alist-replace
-        'unpack
-        (lambda* (#:key inputs #:allow-other-keys)
-          (and (zero? (system* "tar" "xzvf"
-                               (assoc-ref inputs "source")))
-               (chdir ,(mit-scheme-source-directory (%current-system)
-                                                    version))
-               (begin
-                 ;; Delete these dangling symlinks since they break
-                 ;; `patch-shebangs'.
-                 (for-each delete-file
-                           (append '("src/lib/shim-config.scm")
-                                   (find-files "src/lib/lib" "\\.so$")
-                                   (find-files "src/lib" "^liarc-")
-                                   (find-files "src/compiler" "^make\\.")))
-                 (chdir "src")
-                 #t)))
-        (alist-replace
-         'build
-         (lambda* (#:key system outputs #:allow-other-keys)
-           (let ((out (assoc-ref outputs "out")))
-             (if (or (string-prefix? "x86_64" system)
-                     (string-prefix? "i686" system))
-                 (zero? (system* "make" "compile-microcode"))
-                 (zero? (system* "./etc/make-liarc.sh"
-                                 (string-append "--prefix=" out))))))
-         %standard-phases))))
+       (modify-phases %standard-phases
+         (replace 'unpack
+           (lambda* (#:key inputs #:allow-other-keys)
+             (and (zero? (system* "tar" "xzvf"
+                                  (assoc-ref inputs "source")))
+                  (chdir ,(mit-scheme-source-directory (%current-system)
+                                                       version))
+                  (begin
+                    ;; Delete these dangling symlinks since they break
+                    ;; `patch-shebangs'.
+                    (for-each delete-file
+                              (append '("src/lib/shim-config.scm")
+                                      (find-files "src/lib/lib" "\\.so$")
+                                      (find-files "src/lib" "^liarc-")
+                                      (find-files "src/compiler" "^make\\.")))
+                    (chdir "src")
+                    #t))))
+         (replace 'build
+           (lambda* (#:key system outputs #:allow-other-keys)
+             (let ((out (assoc-ref outputs "out")))
+               (if (or (string-prefix? "x86_64" system)
+                       (string-prefix? "i686" system))
+                   (zero? (system* "make" "compile-microcode"))
+                   (zero? (system* "./etc/make-liarc.sh"
+                                   (string-append "--prefix=" out)))))))
+         (add-after 'configure 'configure-doc
+           (lambda* (#:key outputs inputs #:allow-other-keys)
+             (with-directory-excursion "../doc"
+               (let* ((out (assoc-ref outputs "out"))
+                      (bash (assoc-ref inputs "bash"))
+                      (bin/sh (string-append bash "/bin/sh")))
+                 (system* bin/sh "./configure"
+                          (string-append "--prefix=" out)
+                          (string-append "SHELL=" bin/sh))
+                 (substitute* '("Makefile" "make-common")
+                   (("/lib/mit-scheme/doc")
+                    (string-append "/share/doc/" ,name "-" ,version)))
+                 #t))))
+         (add-after 'build 'build-doc
+           (lambda* _
+             (with-directory-excursion "../doc"
+               (zero? (system* "make")))))
+         (add-after 'install 'install-doc
+           (lambda* _
+             (with-directory-excursion "../doc"
+               (zero? (system* "make" "install"))))))))
     (inputs
-     `(;; TODO: Build doc when TeX Live is available.
-       ;; ("automake" ,automake)
-       ;; ("texlive-core" ,texlive-core)
+     `(("texlive" ,texlive)
        ("texinfo" ,texinfo)
        ("m4" ,m4)
        ("libx11" ,libx11)
-- 
2.6.3

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Ludovic Courtès]

Federico Beffa <beffa@ieee.org> skribis:

> From 5c2be0d7d628ba27ac1360cc8e998de68a505b2a Mon Sep 17 00:00:00 2001
> From: Federico Beffa <beffa@fbengineering.ch>
> Date: Sun, 27 Dec 2015 19:06:37 +0100
> Subject: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.
>
> * gnu/packages/scheme.scm (mit-scheme): Convert to the 'modify-phases'
>   syntax. Add phases 'configure-doc, 'build-doc and 'install-doc. Add
>   'texlive' input.

Could you split into two patches: first ‘modify-phases’, then build doc?

I’m a bit concerned about the TeX Live dependency.  I wonder if we
should instead make a separate ‘mit-scheme-doc’ package so that people
don’t have to download/build TeX Live just to build MIT Scheme.  No
strong opinion though.

WDYT?

Thanks,
Ludo’.

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Federico Beffa]

On Tue, Jan 5, 2016 at 11:13 PM, Ludovic Courtès <ludo@gnu.org> wrote:
> Federico Beffa <beffa@ieee.org> skribis:
>
>> * gnu/packages/scheme.scm (mit-scheme): Convert to the 'modify-phases'
>>   syntax. Add phases 'configure-doc, 'build-doc and 'install-doc. Add
>>   'texlive' input.
>
> Could you split into two patches: first ‘modify-phases’, then build doc?

Done.

>
> I’m a bit concerned about the TeX Live dependency.  I wonder if we
> should instead make a separate ‘mit-scheme-doc’ package so that people
> don’t have to download/build TeX Live just to build MIT Scheme.  No
> strong opinion though.
>
> WDYT?

MIT Scheme is a complex system and without the documentation it's not
possible to use it proficiently. Also, currently there is a single
package using mit-scheme as an input (scmutils). For these reasons I
do not think that splitting the documentation to a separate package is
a good idea.

Also, in my opinion giving up on documentation because of the size of
the TeXLive package is bad. If anything the problem should be solved
at the root, i.e., find a way to split it up.

Regards,
Fede

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Ludovic Courtès]

Federico Beffa <beffa@ieee.org> skribis:

> On Tue, Jan 5, 2016 at 11:13 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>> Federico Beffa <beffa@ieee.org> skribis:
>>
>>> * gnu/packages/scheme.scm (mit-scheme): Convert to the 'modify-phases'
>>>   syntax. Add phases 'configure-doc, 'build-doc and 'install-doc. Add
>>>   'texlive' input.
>>
>> Could you split into two patches: first ‘modify-phases’, then build doc?
>
> Done.
>
>>
>> I’m a bit concerned about the TeX Live dependency.  I wonder if we
>> should instead make a separate ‘mit-scheme-doc’ package so that people
>> don’t have to download/build TeX Live just to build MIT Scheme.  No
>> strong opinion though.
>>
>> WDYT?
>
> MIT Scheme is a complex system and without the documentation it's not
> possible to use it proficiently.

Agreed, I didn’t mean to imply we should give up on documentation.

I just realized that its documentation is in Texinfo format.  What about
simply installing the Info format like we do for other GNU packages, and
not the PDF/PS/DVI version?

Thanks,
Ludo’.

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Federico Beffa]

On Sat, Jan 9, 2016 at 7:42 PM, Ludovic Courtès <ludo@gnu.org> wrote:
> Federico Beffa <beffa@ieee.org> skribis:
>> MIT Scheme is a complex system and without the documentation it's not
>> possible to use it proficiently.
>
> Agreed, I didn’t mean to imply we should give up on documentation.
>
> I just realized that its documentation is in Texinfo format.  What about
> simply installing the Info format like we do for other GNU packages, and
> not the PDF/PS/DVI version?

Texinfo is great for looking up pieces of information in a reference
manual. However, when it comes to reading a sizable part, I much prefer
PDFs with a much superior graphic quality and scaling capability and
would like to keep it (my eyes aren't in great conditions). I think we
can drop PS. DVI is not installed. HTML is required by
'emacs-mit-scheme-doc'.

Regards,
Fede

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Ludovic Courtès]

Federico Beffa <beffa@ieee.org> skribis:

> On Sat, Jan 9, 2016 at 7:42 PM, Ludovic Courtès <ludo@gnu.org> wrote:
>> Federico Beffa <beffa@ieee.org> skribis:
>>> MIT Scheme is a complex system and without the documentation it's not
>>> possible to use it proficiently.
>>
>> Agreed, I didn’t mean to imply we should give up on documentation.
>>
>> I just realized that its documentation is in Texinfo format.  What about
>> simply installing the Info format like we do for other GNU packages, and
>> not the PDF/PS/DVI version?
>
> Texinfo is great for looking up pieces of information in a reference
> manual.

You mean Info, right?

> However, when it comes to reading a sizable part, I much prefer PDFs
> with a much superior graphic quality and scaling capability and would
> like to keep it (my eyes aren't in great conditions). I think we can
> drop PS. DVI is not installed. HTML is required by
> 'emacs-mit-scheme-doc'.

One can choose the font family and size for Info documents viewed in
Emacs (or even in a terminal.)  :-)  I find that Info is much more
convenient when reading on a computer because of its interface to
navigate the document, search the indexes, and search for words.

The thing is, we could make an exception for MIT Scheme and provide PDF
and/or HTML in addition to Info.

However, what should we do with the whole set of GNU packages?  I’m
very much in favor of keeping only Info by default, possibly with a few
exceptions.

WDYT?

Ludo’.

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Federico Beffa]

On Sun, Jan 10, 2016 at 7:50 PM, Ludovic Courtès <ludo@gnu.org> wrote:
> Federico Beffa <beffa@ieee.org> skribis:
>> Texinfo is great for looking up pieces of information in a reference
>> manual.
>
> You mean Info, right?

yes.

>
>> However, when it comes to reading a sizable part, I much prefer PDFs
>> with a much superior graphic quality and scaling capability and would
>> like to keep it (my eyes aren't in great conditions). I think we can
>> drop PS. DVI is not installed. HTML is required by
>> 'emacs-mit-scheme-doc'.
>
> One can choose the font family and size for Info documents viewed in
> Emacs (or even in a terminal.)  :-)  I find that Info is much more
> convenient when reading on a computer because of its interface to
> navigate the document, search the indexes, and search for words.

I know that you can choose font and size in emacs and console. But the
fact stays that the rendered quality difference is very large. I do
not know what to add... Many peoples claim not to see much difference.
I and some friends do see a large difference. Obviously the
visual-system varies a lot between peoples.

As said, I agree that for looking up reference information the Info
format is pretty good.

>
> The thing is, we could make an exception for MIT Scheme and provide PDF
> and/or HTML in addition to Info.
>
> However, what should we do with the whole set of GNU packages?  I’m
> very much in favor of keeping only Info by default, possibly with a few
> exceptions.

HTML is not better than Info. Here we only need to keep it for
'emacs-mit-scheme-doc' to work. This is functionality for mit-scheme
whereby Emacs looks up the documentation for the identifier at point.

For PDFs, it depends on the type and quality of the manual. If it is
short and/or poor, then nobody will spend hours reading it. But if the
manual is good and long, then there is a chance that people will spend
a lot of time reading it and it would be nice to have a good quality
environment to read it (again, I'm talking about font graphics
rendering).

This is analogous to making public buildings suitable for people with
wheel-chairs, ... may people don't care, until they are affected :-(

Regards,
Fede

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Mathieu Lirzin]

Hi,

Federico Beffa <beffa@ieee.org> writes:

> HTML is not better than Info. Here we only need to keep it for
> 'emacs-mit-scheme-doc' to work. This is functionality for mit-scheme
> whereby Emacs looks up the documentation for the identifier at point.
>
> For PDFs, it depends on the type and quality of the manual. If it is
> short and/or poor, then nobody will spend hours reading it. But if the
> manual is good and long, then there is a chance that people will spend
> a lot of time reading it and it would be nice to have a good quality
> environment to read it (again, I'm talking about font graphics
> rendering).
>
> This is analogous to making public buildings suitable for people with
> wheel-chairs, ... may people don't care, until they are affected :-(

Sorry I don't understand your analogy.  IIUC the discussion is about
what should be installed with the default output.  Putting the PDF
version of the manual in the 'doc' output will not prevent anyone to use
it.  Did I miss something?

--
Mathieu Lirzin

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Federico Beffa]

On Mon, Jan 11, 2016 at 12:14 AM, Mathieu Lirzin <mthl@gnu.org> wrote:
> Hi,
>
> Federico Beffa <beffa@ieee.org> writes:
>
>> HTML is not better than Info. Here we only need to keep it for
>> 'emacs-mit-scheme-doc' to work. This is functionality for mit-scheme
>> whereby Emacs looks up the documentation for the identifier at point.
>>
>> For PDFs, it depends on the type and quality of the manual. If it is
>> short and/or poor, then nobody will spend hours reading it. But if the
>> manual is good and long, then there is a chance that people will spend
>> a lot of time reading it and it would be nice to have a good quality
>> environment to read it (again, I'm talking about font graphics
>> rendering).
>>
>> This is analogous to making public buildings suitable for people with
>> wheel-chairs, ... may people don't care, until they are affected :-(
>
> Sorry I don't understand your analogy.  IIUC the discussion is about
> what should be installed with the default output.  Putting the PDF
> version of the manual in the 'doc' output will not prevent anyone to use
> it.  Did I miss something?

Well, the discussion is about this sentence:

   I just realized that its documentation is in Texinfo format.  What about
   simply installing the Info format like we do for other GNU packages, and
   not the PDF/PS/DVI version?

I can't find: why don't we put the PDF/PS/DVI in a different output.
If I misunderstood then my bad. But being less cryptic and more
explicit would prevent that.

Regards,
Fede

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Ludovic Courtès]

Federico Beffa <beffa@ieee.org> skribis:

> For PDFs, it depends on the type and quality of the manual. If it is
> short and/or poor, then nobody will spend hours reading it. But if the
> manual is good and long, then there is a chance that people will spend
> a lot of time reading it and it would be nice to have a good quality
> environment to read it (again, I'm talking about font graphics
> rendering).

I agree that rendering is much better in PDF.

> This is analogous to making public buildings suitable for people with
> wheel-chairs, ... may people don't care, until they are affected :-(

I disagree with the analogy.  On a computer, I find it simply less
convenient to browse PDFs than to browse Info, and that outweighs the
better rendering quality.  (As it turns out, Info is also much more
usable for people using a Braille reader.)

When I want to read a complete manual, I prefer the paper version,
though.

> Well, the discussion is about this sentence:
>
>    I just realized that its documentation is in Texinfo format.  What about
>    simply installing the Info format like we do for other GNU packages, and
>    not the PDF/PS/DVI version?
>
> I can't find: why don't we put the PDF/PS/DVI in a different output.

You mean systematically?

There are several reasons Guix does not systematically provide PDF
manuals for GNU packages:

  1. We follow the GNU Standards, which is that ‘make install’ installs
     only Info by default.

  2. There would be technical complications with building PDFs
     systematically (TeX Live is huge, has a lot of dependencies, etc.)

  3. PDFs are quite big and (so I thought) inconvenient when reading on
     a screen, though I now understand that not everyone feels the same.

  4. Until now there hasn’t been demand for it.

So, back to MIT Scheme, what about adding PDFs in a “doc” output, and
installing Info only in “out”?

Regarding the rest of GNU packages, I’m very much in favor of the status
quo, possibly with exceptions like this on a case-by-case basis.

Let me know if you think this is not explicit enough!

Thanks,
Ludo’.

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Federico Beffa]

On Mon, Jan 11, 2016 at 10:09 AM, Ludovic Courtès <ludo@gnu.org> wrote:
> Federico Beffa <beffa@ieee.org> skribis:
>
>> For PDFs, it depends on the type and quality of the manual. If it is
>> short and/or poor, then nobody will spend hours reading it. But if the
>> manual is good and long, then there is a chance that people will spend
>> a lot of time reading it and it would be nice to have a good quality
>> environment to read it (again, I'm talking about font graphics
>> rendering).
>
> I agree that rendering is much better in PDF.
>
>> This is analogous to making public buildings suitable for people with
>> wheel-chairs, ... may people don't care, until they are affected :-(
>
> I disagree with the analogy.  On a computer, I find it simply less
> convenient to browse PDFs than to browse Info, and that outweighs the
> better rendering quality.  (As it turns out, Info is also much more
> usable for people using a Braille reader.)
>
> When I want to read a complete manual, I prefer the paper version,
> though.

It seems you don't get that my point is not about personal preferences
or feelings. It's about physical impairments (and there are plenty of
shades of grays between good sight and completely blind, where big,
good quality fonts matter).

I will install PDFs in a separate output.

Regards,
Fede

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Leo Famulari]

On Mon, Jan 11, 2016 at 12:58:41PM +0100, Federico Beffa wrote:
> On Mon, Jan 11, 2016 at 10:09 AM, Ludovic Courtès <ludo@gnu.org> wrote:
> > Federico Beffa <beffa@ieee.org> skribis:
> >
> >> For PDFs, it depends on the type and quality of the manual. If it is
> >> short and/or poor, then nobody will spend hours reading it. But if the
> >> manual is good and long, then there is a chance that people will spend
> >> a lot of time reading it and it would be nice to have a good quality
> >> environment to read it (again, I'm talking about font graphics
> >> rendering).
> >
> > I agree that rendering is much better in PDF.
> >
> >> This is analogous to making public buildings suitable for people with
> >> wheel-chairs, ... may people don't care, until they are affected :-(
> >
> > I disagree with the analogy.  On a computer, I find it simply less
> > convenient to browse PDFs than to browse Info, and that outweighs the
> > better rendering quality.  (As it turns out, Info is also much more
> > usable for people using a Braille reader.)
> >
> > When I want to read a complete manual, I prefer the paper version,
> > though.
> 
> It seems you don't get that my point is not about personal preferences
> or feelings. It's about physical impairments (and there are plenty of
> shades of grays between good sight and completely blind, where big,
> good quality fonts matter).

Agreed, I know two people with very severe visual impairments who find
it more effective to magnify text to what seems an extreme degree than
to use a Braille reader.

> 
> I will install PDFs in a separate output.
> 
> Regards,
> Fede
> 

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Ludovic Courtès]

Federico Beffa <beffa@ieee.org> skribis:

> On Mon, Jan 11, 2016 at 10:09 AM, Ludovic Courtès <ludo@gnu.org> wrote:
>> Federico Beffa <beffa@ieee.org> skribis:
>>
>>> For PDFs, it depends on the type and quality of the manual. If it is
>>> short and/or poor, then nobody will spend hours reading it. But if the
>>> manual is good and long, then there is a chance that people will spend
>>> a lot of time reading it and it would be nice to have a good quality
>>> environment to read it (again, I'm talking about font graphics
>>> rendering).
>>
>> I agree that rendering is much better in PDF.
>>
>>> This is analogous to making public buildings suitable for people with
>>> wheel-chairs, ... may people don't care, until they are affected :-(
>>
>> I disagree with the analogy.  On a computer, I find it simply less
>> convenient to browse PDFs than to browse Info, and that outweighs the
>> better rendering quality.  (As it turns out, Info is also much more
>> usable for people using a Braille reader.)

[...]

> It seems you don't get that my point is not about personal preferences
> or feelings. It's about physical impairments (and there are plenty of
> shades of grays between good sight and completely blind, where big,
> good quality fonts matter).

My point about Braille reader is very clearly about physical
impairment.  I think I do get your point.

Ludo’.

Re: [PATCH 5/6] gnu: mit-scheme: Generate and install documentation.

[Federico Beffa]

On Mon, Jan 11, 2016 at 8:06 PM, Leo Famulari <leo@famulari.name> wrote:
>> It seems you don't get that my point is not about personal preferences
>> or feelings. It's about physical impairments (and there are plenty of
>> shades of grays between good sight and completely blind, where big,
>> good quality fonts matter).
>
> Agreed, I know two people with very severe visual impairments who find
> it more effective to magnify text to what seems an extreme degree than
> to use a Braille reader.

Thanks for sharing your experience supporting my claim!

Regards,
Fede