Bug 240244 - sysutils/conky Documentation files are empty
Summary: sysutils/conky Documentation files are empty
Status: Closed FIXED
Alias: None
Product: Ports & Packages
Classification: Unclassified
Component: Individual Port(s) (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: Guido Falsi
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2019-09-01 04:12 UTC by James Stark
Modified: 2019-09-02 07:12 UTC (History)
1 user (show)

See Also:
madpilot: maintainer-feedback+
madpilot: merge-quarterly+


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description James Stark 2019-09-01 04:12:12 UTC
Conky's documentation is installed by the package but the files are empty.

ls -l /usr/local/share/doc/conky/html
-rw-r--r--  1 root  wheel  0 Aug 22 13:03 config_settings.html
-rw-r--r--  1 root  wheel  0 Aug 22 13:02 docs.html
-rw-r--r--  1 root  wheel  0 Aug 22 13:03 lua.html
-rw-r--r--  1 root  wheel  0 Aug 22 13:03 variables.html
Comment 1 Guido Falsi freebsd_committer 2019-09-01 08:32:21 UTC
Hi,

Thanks for the report.

I did not notice this. From what I can see in the build logs, something goes wrong when these files are generated from source using various tools.

This is strange especially because if I follow those same steps by hand on my machine everything works fine. I need some time to investigate what is actually happening.
Comment 2 Rainer Hurling freebsd_committer 2019-09-01 09:51:25 UTC
There is another problem with conky port, when it tries to build its documentation:


===>  docbook2X-0.8.8_5 conflicts with installed package(s): 
      docbook-utils-0.6.14_13

      They install files into the same place.


textproc/docbook-utils is needed on my boxes (13.0-CURRENT) for several other ports, built via portmaster.

Do you think it is possible to abstain from docbook2X and use docbook-utils or something other instead?
Comment 3 Guido Falsi freebsd_committer 2019-09-01 10:41:08 UTC
(In reply to Rainer Hurling from comment #2)

This is not a port's problem. It's a local problem to your specific machine.

The port requires that port to build documentation. The conflict is there for a reason, and can't be ignored.

Building ports directly on live machines is not a best practice nowadays, for a lot of reasons, one of which is that a live machine has many things installed and many configurations which can (and will) interfere with the build, sometimes in evident ways like this, some other times the interference could be more subtle.

Also, due to the ways the world is going, I have seen this kind of issues getting worse this time and it's not going to get better. Main cause is that all other operating systems are building open source packages in isolation and users are using binary packages or building their own with dedicated software. Software is developed primarily for such build environments, and growing dependencies.

If you don't strictly need the latest version in an hurry and don't strictly need customized options, using the official binary packages today is really easy and they work quite well (while I agree the old pkg_install based binary packages used to have lots of problems).

Otherwise if you need custom built packages you should really investigate using poudriere or similar software (available in the ports tree) so you are sure packages are built in a clean environment.

Anyway in this case I can add knobs to the Makefile to skip building the documentation when the DOC option is deselected, and not depend on the ports required for that step.
Comment 4 Rainer Hurling freebsd_committer 2019-09-01 11:36:47 UTC
(In reply to Guido Falsi from comment #3)

Many thanks for the answer.

> This is not a port's problem. It's a local problem to your specific machine.
Not sysutils/conky, but it is an existing conflict between textproc/docbook-utils and textproc/docbook2X.

> The port requires that port to build documentation. The conflict is there
> for a reason, and can't be ignored.
Agreed.

> Building ports directly on live machines is not a best practice nowadays,
> for a lot of reasons, one of which is that a live machine has many things
> installed and many configurations which can (and will) interfere with the
> build, sometimes in evident ways like this, some other times the
> interference could be more subtle.
On some machines, for example to adapt GIS applications (in my case graphics/qgis, math/saga) one needs to play with ports options of several depending ports (here graphics/gdal, databases/grass7, graphics/geos, ...) in many combinations. This is not very handy in environments like Poudriere, but relatively fast with 'make install' or portmaster.

> Also, due to the ways the world is going, I have seen this kind of issues
> getting worse this time and it's not going to get better. Main cause is
> that all other operating systems are building open source packages in
> isolation and users are using binary packages or building their own with
> dedicated software. Software is developed primarily for such build
> environments, and growing dependencies.
> If you don't strictly need the latest version in an hurry and don't
> strictly need customized options, using the official binary packages
> today is really easy and they work quite well (while I agree the old
> pkg_install based binary packages used to have lots of problems).
Thanks for the detailed explanation. For me, this approach is known already. I am not talking of a production box, but one for develepment with often changing configurations (especially ports options).

> Otherwise if you need custom built packages you should really investigate
> using poudriere or similar software (available in the ports tree) so you
> are sure packages are built in a clean environment.
I do also use Poudriere and I like it.

In this special case it is a conflict with an already installed port textproc/docbook-utils, used by other installed ports, and building a port like sysutils/conky, which depends on textproc/docbook2X in the build phase. 
The question behind is, shouldn't it be possible to use both ports (docbook2X and docbook-utils) on the same box at the same time (no conflicts)? In your direction as the maintainer of conky port I would like to ask, if it is possible to circumstand that conflict by using something else than textproc/docbook2X to build sysutils/conky documentation.

> Anyway in this case I can add knobs to the Makefile to skip building the
> documentation when the DOC option is deselected, and not depend on the
> ports required for that step.
I do not think, that this is necessary. If it is only me, I for myself can patch conky locally on my dev boxes or uninstall/reinstall textproc/docbook-utils before conky builds. But thanks for the offer.

Thanks for maintaining this interesting port.
Comment 5 Guido Falsi freebsd_committer 2019-09-01 13:43:49 UTC
(In reply to Rainer Hurling from comment #4)

(I'm unable to get bugzilla to quote your message, doing it manually, hope output will not be mangled)

> On some machines, for example to adapt GIS applications (in my case
> graphics/qgis, math/saga) one needs to play with ports options of
> several depending ports (here graphics/gdal, databases/grass7,
> graphics/geos, ...) in many combinations. This is not very handy in
> environments like Poudriere, but relatively fast with 'make install'
> or portmaster.

Obviously you can use whatever tool you see fit and maybe I don't understand your setup.

But I don't understand where the problem is. poudriere caan handle options on a per jail/portsrtree/set criteria. You can have a bunch of sets of ports built with different options. There is the "options" subcommand to help you set options for each port in each of those separations.

> In this special case it is a conflict with an already installed port
> textproc/docbook-utils, used by other installed ports, and building a
> port like sysutils/conky, which depends on textproc/docbook2X in the
> build phase. 
> The question behind is, shouldn't it be possible to use both ports
> (docbook2X and docbook-utils) on the same box at the same time (no conflicts)?

The conflict because they both install files in the same locations on disk, so, no it should not. That's how the whole ports/package system was made.

You could try installing them to different PREFIX, but it has it's drawbacks, like requiring a custom PATH.

To resolve the conflict you should get one of the maintainers of one of those ports change it to install things in a different location, or with a different name.

> In your direction as the maintainer of conky port I would like to ask, if
> it is possible to circumstand that conflict by using something else than
> textproc/docbook2X to build sysutils/conky documentation.

I don't know. The ports contain just that, ports. The upstream project uses the db2x_xsltproc and db2x_manxml commands to build the man page. Those commands are provided by the textproc/docbook2X port.

If you know of some equivalent command provided by another port I can test it.

Otherwise, the documentation is built by the doc/docgen.sh script in the conky sources (which is slightly patched in the port to not grab the xsl file from the web but to use the local one). If you want you can modify that file to produce it's documentation some other way, by using whatever tool you see fit.

Patches are always welcome. Keep in mind that this would make the port diverge from upstream, and any patch should be created in such a way to be proposed to the upstream developer.
Comment 6 Guido Falsi freebsd_committer 2019-09-01 13:45:26 UTC
(In reply to Rainer Hurling from comment #2)

Btw your request is unrelated to the original content of this bug report.

I'm going to commit the patch to resolve the original problem and close this bug. Please file a new one for your specific problem so it can be properly tracked.
Comment 7 Rainer Hurling freebsd_committer 2019-09-01 16:41:20 UTC
(In reply to Guido Falsi from comment #5 and comment #6)

I also did quoting your message manually before ;)

For now, I have no other idea how to solve the conflict between docbook2X and docbook-utils than the one, you already mentioned: Asking one of the maintainers to change the naming or to install things in a different location.

Yes and sorry, my request is a bit unrelated to the original content of this bug report. It was in the hope, that 'repairing' the documentation could also help here.

And of course, you will close this bug after solving the original problem.

Many thanks again.
Comment 8 Guido Falsi freebsd_committer 2019-09-01 19:24:45 UTC
Fix committed.

Thanks!

Waiting for MFH.
Comment 9 commit-hook freebsd_committer 2019-09-01 19:24:54 UTC
A commit references this bug:

Author: madpilot
Date: Sun Sep  1 19:23:54 UTC 2019
New revision: 510734
URL: https://svnweb.freebsd.org/changeset/ports/510734

Log:
  Fix document generation.

  PR:		240244
  Submitted by:	James Stark <james.e.stark@gmail.com>
  MFH:		2019Q3

Changes:
  head/sysutils/conky/Makefile
  head/sysutils/conky/files/patch-doc_docgen.sh
Comment 10 commit-hook freebsd_committer 2019-09-02 07:10:51 UTC
A commit references this bug:

Author: madpilot
Date: Mon Sep  2 07:10:32 UTC 2019
New revision: 510765
URL: https://svnweb.freebsd.org/changeset/ports/510765

Log:
  MFH: r510734

  Fix document generation.

  PR:		240244
  Submitted by:	James Stark <james.e.stark@gmail.com>

  Approved by:	ports-secteam (joneum)

Changes:
_U  branches/2019Q3/
  branches/2019Q3/sysutils/conky/Makefile
  branches/2019Q3/sysutils/conky/files/patch-doc_docgen.sh
Comment 11 Guido Falsi freebsd_committer 2019-09-02 07:12:06 UTC
Merged to quarterly.

Thanks!