Subject: bug#37850: Glib documentation is missing

From: Marius Bakke <[email-masked]>
Date: Sun, 10 Nov 2019 00:20:14 +0100

Pierre Neidhardt <[email-masked]> writes:

> Marius Bakke <[email-masked]> writes:
>
>> Pierre Neidhardt <[email-masked]> writes:
>>
>>> From 893613a3b99c20688cc331d2926dbee28cc143d7 Mon Sep 17 00:00:00 2001
>>> From: Pierre Neidhardt <[email-masked]>
>>> Date: Sun, 3 Nov 2019 17:36:17 +0100
>>> Subject: [PATCH] gnu: Add glib-minimal and build glib doc.
>>>
>>> glib documentation must be built with gtk-doc which in turn depends on glib,
>>> so we need to define glib-minimal which does not depend on gtk-doc.
>>>
>>> * gnu/packages/glib.scm (glib-minimal): New variable.
>>> (glib)[source]: Don't use `name'.
>>> * gnu/packages/avahi.scm: Use glib-minimal when necessary.
>>> * gnu/packages/cups.scm: Use glib-minimal when necessary.
>>> * gnu/packages/gnome.scm: Use glib-minimal when necessary.
>>> * gnu/packages/graphviz.scm: Use glib-minimal when necessary.
>>> * gnu/packages/gtk.scm: Use glib-minimal when necessary.
>>> * gnu/packages/inkscape.scm: Use glib-minimal when necessary.
>>> * gnu/packages/pdf.scm: Use glib-minimal when necessary.
>>
>> Please mention all changed variables and inputs here, as we always do.
>
> Sure, I didn't because I wasn't sure it was a good idea either :p
>
>> That said, I'm not certain this is a good solution.  Why do some
>> packages use glib-minimal and others not?  What does "necessary" mean in
>> this context?
>>
>> What about 'hiding' the normal glib package, and expose a
>> 'glib-with-documentation' variant to end users, similar to how the
>> 'cmake' package works?
>
> cmake-minimal builds the doc already, I don't see a
> cmake-with-documentation.  Did you mean something else?
> I see a couple packages with the "-documentation" prefix, so we could
> use "glib-documentation".

I meant this part:

(define-public cmake
  (package
    (inherit cmake-minimal)
    (name "cmake")
    (arguments
     (substitute-keyword-arguments (package-arguments cmake-minimal)
       ((#:configure-flags configure-flags ''())
        `(append ,configure-flags
                ;; Extra configure flags used to generate the documentation.
                '("--sphinx-info"
                  "--sphinx-man"
                  "--sphinx-html")))

Do you think it would make sense to do something similar with GLib,
and "hiding" the normal variant?

> In a previous email, I explained that I wanted to put the documentation
> in the "doc" output of glib for 2 reasons:
>
> - For consistency with the other packages from the GTK family.
> - To restore the missing "gtk:doc" output.  If I understand correctly,
>   we don't have a provision to deprecate outputs, only packages.  I
>   think this is a bug.