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

[Eric Bavier]

On Fri, 08 Jan 2016 11:19:34 +0100
address@hidden (Ludovic Courtès) wrote:

> Eric Bavier <address@hidden> skribis:
> 
> > From c8a0086db4d78091e06326a5ffe55a7bf2543091 Mon Sep 17 00:00:00 2001
> > From: Eric Bavier <address@hidden>
> > 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.

I sometimes find PDF documentation more visually appealing, but only if
they having functioning hyperlinks.  Which unison's pdf docs lack,
so yes, I think we can install just the HTML.

> 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.

However, it appears the unison-manual.tex needs to be run through LaTeX
at least once in order to get a TOC for hevea to include in the html
output.  So it seems we can't remove TeX Live.  Sigh...
 
> WDYT?

I don't want to spend much more time on this, so I think I'll push a
slight modification of this patch that just doesn't install the pdf,
ps, and dvi output for the sake a reproducibility.

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

Info > HTML > man > txt > PDF > PS ?

> Thanks for finding out how to build documentation from source!

No problem; kinda fun. :)

`~Eric