Re: [PATCH] gnu: unison: Add "doc" output.

[ludo@gnu.org (Ludovic Courtès)]

Eric Bavier <ericbavier@openmailbox.org> skribis:

> From c8a0086db4d78091e06326a5ffe55a7bf2543091 Mon Sep 17 00:00:00 2001
> From: Eric Bavier <bavier@member.fsf.org>
> Date: Fri, 18 Dec 2015 19:29:22 -0600
> Subject: [PATCH] gnu: unison: Add "doc" output.
>
> * gnu/packages/ocaml.scm (unison)[source]: Use svn-fetch with snippet.
>   [outputs]: New field.
>   [native-inputs]: Add ghostscript, texlive, hevea, and lynx.
>   [arguments]: Add 'install-doc phase.

[...]

> +        (snippet
> +         `(begin
> +            ;; The svn revision in the release tarball appears to be
> +            ;; artificially manipulated in order to set the desired point
> +            ;; version number.  Because the point version is calculated during
> +            ;; the build, we can offset pointVersionOrigin by the desired
> +            ;; point version and write that into "Rev: %d".  We do this rather
> +            ;; than hardcoding the necessary revision number, for
> +            ;; maintainability.

Fun.  :-)

> +            (with-atomic-file-replacement "src/mkProjectInfo.ml"
> +              (lambda (in out)
> +                (let ((pt-ver (string->number (third (string-split ,version #\.))))
> +                      (pt-rx  (make-regexp "^let pointVersionOrigin = ([0-9]+)"))
> +                      (rev-rx (make-regexp "Rev: [0-9]+")))
> +                  (let loop ((pt-origin #f))
> +                    (let ((line (read-line in 'concat)))
> +                      (cond
> +                       ((regexp-exec pt-rx line)
> +                        => (lambda (m)
> +                             (begin

‘begin’ can be omitted here…

> +                       ((regexp-exec rev-rx line)
> +                        => (lambda (m)
> +                             (begin

… and here.

> +                        (for-each (lambda (f)
> +                                    (install-file f doc))
> +                                  (map (lambda (ext)
> +                                         (string-append
> +                                          "doc/unison-manual." ext))
> +                                       '("ps" "pdf" "dvi" "html")))

What about installing only HTML?

I find that HTML (and Info, and man) is more convenient to read on-line
than PDFs.  We rarely include PDF documentation in packages.

Of course, avoiding PDF/PS/DVI allows us to remove the dependency on
TeX Live.  Last, from discussions I heard at the Reproducible Build
Summit, I think DVIs and maybe PS/PDFs are not bit-reproducible
out-of-the-box.

WDYT?

Maybe we should have a policy on how to choose the installed
documentation formats.

Thanks for finding out how to build documentation from source!

Ludo’.