Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-26 Thread Ben Pfaff 
On Wed, Apr 26, 2017 at 04:00:55PM +0100, Stephen Finucane wrote:
> On Wed, 2017-04-26 at 10:55 -0400, Lance Richardson wrote:
> > > From: "Ben Pfaff" <b...@ovn.org>
> > > To: "Lance Richardson" <lrich...@redhat.com>
> > > Cc: "Leif Madsen" <lmad...@redhat.com>, "ovs dev" <dev@openvswitch.
> > > org>
> > > Sent: Wednesday, 26 April, 2017 10:33:09 AM
> > > Subject: Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST
> > > 
> > > On Tue, Apr 25, 2017 at 04:03:55PM -0400, Lance Richardson wrote:
> > > > I ran into this a little while ago. The problem in my case was
> > > > that
> > > > sphinx-build
> > > > was not installed, so these man pages were not being built (seems
> > > > odd that
> > > > this
> > > > would not cause a build failure...)
> > > > 
> > > > Doing "yum install python-sphinx" let me build the rpms
> > > > successfully once
> > > > again. Seems we should add "BuildRequires: python-sphinx" to the
> > > > spec file.
> > > 
> > > Huh.  Somehow I thought that we'd made Sphinx an overall build
> > > requirement.  Maybe that's the right thing to do.
> > > 
> > 
> > The rules to build rst-formatted man pages in the top-level
> > Makefile.in are predicated on HAVE_SPHINX_TRUE, which does give the
> > impression that Sphinx is optional.
> > 
> >    Lance
> 
> Yup, it's optional since these were only used for HTML docs initially.
> I didn't change that as HAVE_GROFF is also a thing, afaict, and I
> wasn't sure if man pages were essential. Maybe they should be now.

HAVE_GROFF might be a deceptive example, because the availability of
groff only affects whether the build can do a little bit of checking of
the manpages' syntax at build time.  It doesn't affect whether manpages
can be built; they always can be.

I'm inclined to try making Sphinx a hard requirement for the build, and
then relaxing that if it proves untenable in practice.
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-26 Thread Lance Richardson 
> From: "Stephen Finucane" <step...@that.guru>
> To: "Lance Richardson" <lrich...@redhat.com>, "Ben Pfaff" <b...@ovn.org>
> Cc: "ovs dev" <d...@openvswitch.org>
> Sent: Wednesday, 26 April, 2017 11:00:55 AM
> Subject: Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST
> 
> On Wed, 2017-04-26 at 10:55 -0400, Lance Richardson wrote:
> > > From: "Ben Pfaff" <b...@ovn.org>
> > > To: "Lance Richardson" <lrich...@redhat.com>
> > > Cc: "Leif Madsen" <lmad...@redhat.com>, "ovs dev" <dev@openvswitch.
> > > org>
> > > Sent: Wednesday, 26 April, 2017 10:33:09 AM
> > > Subject: Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST
> > > 
> > > On Tue, Apr 25, 2017 at 04:03:55PM -0400, Lance Richardson wrote:
> > > > I ran into this a little while ago. The problem in my case was
> > > > that
> > > > sphinx-build
> > > > was not installed, so these man pages were not being built (seems
> > > > odd that
> > > > this
> > > > would not cause a build failure...)
> > > > 
> > > > Doing "yum install python-sphinx" let me build the rpms
> > > > successfully once
> > > > again. Seems we should add "BuildRequires: python-sphinx" to the
> > > > spec file.
> > > 
> > > Huh.  Somehow I thought that we'd made Sphinx an overall build
> > > requirement.  Maybe that's the right thing to do.
> > > 
> > 
> > The rules to build rst-formatted man pages in the top-level
> > Makefile.in are predicated on HAVE_SPHINX_TRUE, which does give the
> > impression that Sphinx is optional.
> > 
> >    Lance
> 
> Yup, it's optional since these were only used for HTML docs initially.
> I didn't change that as HAVE_GROFF is also a thing, afaict, and I
> wasn't sure if man pages were essential. Maybe they should be now.
> 

It seems fine to me to handle this by having stricter requirements for
packaging than for the base build (as they need to be anyway). OTOH there
would be some benefits to making it a requirement for the base build, such
as catching build errors earlier.

   Lance

> Stephen
> 
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-26 Thread Leif Madsen 
On Wed, Apr 26, 2017 at 11:00 AM, Stephen Finucane 
wrote:

> On Wed, 2017-04-26 at 10:55 -0400, Lance Richardson wrote:
> > The rules to build rst-formatted man pages in the top-level
> > Makefile.in are predicated on HAVE_SPHINX_TRUE, which does give the
> > impression that Sphinx is optional.
>
> Yup, it's optional since these were only used for HTML docs initially.
> I didn't change that as HAVE_GROFF is also a thing, afaict, and I
> wasn't sure if man pages were essential. Maybe they should be now.


Looks like it might not be optional now (at least for package building). I
can confirm 100% now that the change Lance provided does result in
successful builds.

Leif.
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-26 Thread Stephen Finucane 
On Wed, 2017-04-26 at 10:55 -0400, Lance Richardson wrote:
> > From: "Ben Pfaff" <b...@ovn.org>
> > To: "Lance Richardson" <lrich...@redhat.com>
> > Cc: "Leif Madsen" <lmad...@redhat.com>, "ovs dev" <dev@openvswitch.
> > org>
> > Sent: Wednesday, 26 April, 2017 10:33:09 AM
> > Subject: Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST
> > 
> > On Tue, Apr 25, 2017 at 04:03:55PM -0400, Lance Richardson wrote:
> > > I ran into this a little while ago. The problem in my case was
> > > that
> > > sphinx-build
> > > was not installed, so these man pages were not being built (seems
> > > odd that
> > > this
> > > would not cause a build failure...)
> > > 
> > > Doing "yum install python-sphinx" let me build the rpms
> > > successfully once
> > > again. Seems we should add "BuildRequires: python-sphinx" to the
> > > spec file.
> > 
> > Huh.  Somehow I thought that we'd made Sphinx an overall build
> > requirement.  Maybe that's the right thing to do.
> > 
> 
> The rules to build rst-formatted man pages in the top-level
> Makefile.in are predicated on HAVE_SPHINX_TRUE, which does give the
> impression that Sphinx is optional.
> 
>    Lance

Yup, it's optional since these were only used for HTML docs initially.
I didn't change that as HAVE_GROFF is also a thing, afaict, and I
wasn't sure if man pages were essential. Maybe they should be now.

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-26 Thread Lance Richardson 
> From: "Ben Pfaff" <b...@ovn.org>
> To: "Lance Richardson" <lrich...@redhat.com>
> Cc: "Leif Madsen" <lmad...@redhat.com>, "ovs dev" <d...@openvswitch.org>
> Sent: Wednesday, 26 April, 2017 10:33:09 AM
> Subject: Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST
> 
> On Tue, Apr 25, 2017 at 04:03:55PM -0400, Lance Richardson wrote:
> > I ran into this a little while ago. The problem in my case was that
> > sphinx-build
> > was not installed, so these man pages were not being built (seems odd that
> > this
> > would not cause a build failure...)
> > 
> > Doing "yum install python-sphinx" let me build the rpms successfully once
> > again. Seems we should add "BuildRequires: python-sphinx" to the spec file.
> 
> Huh.  Somehow I thought that we'd made Sphinx an overall build
> requirement.  Maybe that's the right thing to do.
> 

The rules to build rst-formatted man pages in the top-level Makefile.in
are predicated on HAVE_SPHINX_TRUE, which does give the impression that Sphinx
is optional.

   Lance
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-26 Thread Leif Madsen 
On Wed, Apr 26, 2017 at 10:33 AM, Ben Pfaff  wrote:

> On Tue, Apr 25, 2017 at 04:03:55PM -0400, Lance Richardson wrote:
> > I ran into this a little while ago. The problem in my case was that
> sphinx-build
> > was not installed, so these man pages were not being built (seems odd
> that this
> > would not cause a build failure...)
> >
> > Doing "yum install python-sphinx" let me build the rpms successfully once
> > again. Seems we should add "BuildRequires: python-sphinx" to the spec
> file.
>
> Huh.  Somehow I thought that we'd made Sphinx an overall build
> requirement.  Maybe that's the right thing to do.
>

Unfortunately, actually, the build failed (what I saw must have been an out
of date build that succeeded). I'm going to test locally and I'll get back
to you :)

Leif.
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-26 Thread Ben Pfaff 
On Tue, Apr 25, 2017 at 04:03:55PM -0400, Lance Richardson wrote:
> I ran into this a little while ago. The problem in my case was that 
> sphinx-build
> was not installed, so these man pages were not being built (seems odd that 
> this
> would not cause a build failure...)
> 
> Doing "yum install python-sphinx" let me build the rpms successfully once
> again. Seems we should add "BuildRequires: python-sphinx" to the spec file.

Huh.  Somehow I thought that we'd made Sphinx an overall build
requirement.  Maybe that's the right thing to do.
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-26 Thread Leif Madsen 
This is indeed the correct approach it seems. I've validated that adding
Lance's change results in a successful build with the original globs. I'll
ACK his patch here in a moment.

Thanks!
Leif.

On Tue, Apr 25, 2017 at 4:03 PM, Lance Richardson <lrich...@redhat.com>
wrote:

> > From: "Ben Pfaff" <b...@ovn.org>
> > To: "Leif Madsen" <lmad...@redhat.com>
> > Cc: "ovs dev" <d...@openvswitch.org>
> > Sent: Monday, 24 April, 2017 5:02:28 PM
> > Subject: Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST
> >
> > On Mon, Apr 24, 2017 at 04:37:51PM -0400, Leif Madsen wrote:
> > > On Mon, Apr 24, 2017 at 3:57 PM, Ben Pfaff <b...@ovn.org> wrote:
> > >
> > > > On Mon, Apr 24, 2017 at 03:52:53PM -0400, Leif Madsen wrote:
> > > > > I think this change might have broken packaging :)
> > > > >
> > > > > I just tested, and with the removal / renaming of the man8 pages
> for
> > > > > ovs-test and ovs-vlan-test, the RPM fails to build because of
> missing
> > > > files
> > > > > that no longer match the glob.
> > > > >
> > > > > These two lines need to be removed from the build:
> > > > >
> > > > > 471 %{_mandir}/man8/ovs-test.8*
> > > > > 472 %{_mandir}/man8/ovs-vlan-test.8*
> > > > >
> > > > >
> > > > > I'll submit a patch shortly.
> > > >
> > > > OK, I'm confused then.  There was no removal or renaming of the
> > > > installed man8 pages, only of the source files.  So, when I run "make
> > > > install DESTDIR=$PWD/inst", I get a file
> > > > inst/usr/share/man/man8/ovs-test.8 installed, and that should be the
> > > > same as before.
> > > >
> > > > Any idea what's going on?
> > > >
> > >
> > > Huh, well then I'm very confused as well :)
> > >
> > > I just did a test, and things seem to build fine when I remove those
> two
> > > lines. Otherwise, the RPM will fail to build with the following:
> > >
> > > Processing files:
> > > openvswitch-test-2.7.90.14191.git3570f7e4-1.el7.centos.noarch
> > > error: File not found by glob:
> > > /builddir/build/BUILDROOT/openvswitch-2.7.90.14191.
> git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-test.8*
> > > error: File not found by glob:
> > > /builddir/build/BUILDROOT/openvswitch-2.7.90.14191.
> git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-vlan-test.8*
> > >
> > >
> > > RPM build errors:
> > > File not found by glob:
> > > /builddir/build/BUILDROOT/openvswitch-2.7.90.14191.
> git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-test.8*
> > > File not found by glob:
> > > /builddir/build/BUILDROOT/openvswitch-2.7.90.14191.
> git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-vlan-test.8*
> > >
>
> I ran into this a little while ago. The problem in my case was that
> sphinx-build
> was not installed, so these man pages were not being built (seems odd that
> this
> would not cause a build failure...)
>
> Doing "yum install python-sphinx" let me build the rpms successfully once
> again. Seems we should add "BuildRequires: python-sphinx" to the spec file.
>
> Regards,
>
>Lance
>



-- 
Leif Madsen | Partner Engineer - NFV & CI
NFV Partner Engineering
Red Hat
GPG: (D670F846) BEE0 336E 5406 42BA 6194 6831 B38A 291E D670 F846
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-25 Thread Lance Richardson 
> From: "Ben Pfaff" <b...@ovn.org>
> To: "Leif Madsen" <lmad...@redhat.com>
> Cc: "ovs dev" <d...@openvswitch.org>
> Sent: Monday, 24 April, 2017 5:02:28 PM
> Subject: Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST
> 
> On Mon, Apr 24, 2017 at 04:37:51PM -0400, Leif Madsen wrote:
> > On Mon, Apr 24, 2017 at 3:57 PM, Ben Pfaff <b...@ovn.org> wrote:
> > 
> > > On Mon, Apr 24, 2017 at 03:52:53PM -0400, Leif Madsen wrote:
> > > > I think this change might have broken packaging :)
> > > >
> > > > I just tested, and with the removal / renaming of the man8 pages for
> > > > ovs-test and ovs-vlan-test, the RPM fails to build because of missing
> > > files
> > > > that no longer match the glob.
> > > >
> > > > These two lines need to be removed from the build:
> > > >
> > > > 471 %{_mandir}/man8/ovs-test.8*
> > > > 472 %{_mandir}/man8/ovs-vlan-test.8*
> > > >
> > > >
> > > > I'll submit a patch shortly.
> > >
> > > OK, I'm confused then.  There was no removal or renaming of the
> > > installed man8 pages, only of the source files.  So, when I run "make
> > > install DESTDIR=$PWD/inst", I get a file
> > > inst/usr/share/man/man8/ovs-test.8 installed, and that should be the
> > > same as before.
> > >
> > > Any idea what's going on?
> > >
> > 
> > Huh, well then I'm very confused as well :)
> > 
> > I just did a test, and things seem to build fine when I remove those two
> > lines. Otherwise, the RPM will fail to build with the following:
> > 
> > Processing files:
> > openvswitch-test-2.7.90.14191.git3570f7e4-1.el7.centos.noarch
> > error: File not found by glob:
> > /builddir/build/BUILDROOT/openvswitch-2.7.90.14191.git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-test.8*
> > error: File not found by glob:
> > /builddir/build/BUILDROOT/openvswitch-2.7.90.14191.git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-vlan-test.8*
> > 
> > 
> > RPM build errors:
> > File not found by glob:
> > /builddir/build/BUILDROOT/openvswitch-2.7.90.14191.git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-test.8*
> > File not found by glob:
> > /builddir/build/BUILDROOT/openvswitch-2.7.90.14191.git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-vlan-test.8*
> > 

I ran into this a little while ago. The problem in my case was that sphinx-build
was not installed, so these man pages were not being built (seems odd that this
would not cause a build failure...)

Doing "yum install python-sphinx" let me build the rpms successfully once
again. Seems we should add "BuildRequires: python-sphinx" to the spec file.

Regards,

   Lance
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-24 Thread Ben Pfaff 
On Mon, Apr 24, 2017 at 04:37:51PM -0400, Leif Madsen wrote:
> On Mon, Apr 24, 2017 at 3:57 PM, Ben Pfaff  wrote:
> 
> > On Mon, Apr 24, 2017 at 03:52:53PM -0400, Leif Madsen wrote:
> > > I think this change might have broken packaging :)
> > >
> > > I just tested, and with the removal / renaming of the man8 pages for
> > > ovs-test and ovs-vlan-test, the RPM fails to build because of missing
> > files
> > > that no longer match the glob.
> > >
> > > These two lines need to be removed from the build:
> > >
> > > 471 %{_mandir}/man8/ovs-test.8*
> > > 472 %{_mandir}/man8/ovs-vlan-test.8*
> > >
> > >
> > > I'll submit a patch shortly.
> >
> > OK, I'm confused then.  There was no removal or renaming of the
> > installed man8 pages, only of the source files.  So, when I run "make
> > install DESTDIR=$PWD/inst", I get a file
> > inst/usr/share/man/man8/ovs-test.8 installed, and that should be the
> > same as before.
> >
> > Any idea what's going on?
> >
> 
> Huh, well then I'm very confused as well :)
> 
> I just did a test, and things seem to build fine when I remove those two
> lines. Otherwise, the RPM will fail to build with the following:
> 
> Processing files:
> openvswitch-test-2.7.90.14191.git3570f7e4-1.el7.centos.noarch
> error: File not found by glob:
> /builddir/build/BUILDROOT/openvswitch-2.7.90.14191.git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-test.8*
> error: File not found by glob:
> /builddir/build/BUILDROOT/openvswitch-2.7.90.14191.git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-vlan-test.8*
> 
> 
> RPM build errors:
> File not found by glob:
> /builddir/build/BUILDROOT/openvswitch-2.7.90.14191.git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-test.8*
> File not found by glob:
> /builddir/build/BUILDROOT/openvswitch-2.7.90.14191.git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-vlan-test.8*
> 
> 
> 
> So I'm not entirely sure why my build isn't resulting in those files. I
> have everything being built from a script and done in mock, so things
> should be quite reproducable. I see the same failure both on my COPR repo,
> and in my local build environment.

I don't really have a RPM build environment (my main distro is Debian),
but can I suggest an experiment?  Something like this:

diff --git a/rhel/openvswitch-fedora.spec.in b/rhel/openvswitch-fedora.spec.in
index dbcab00cd428..1d43ebe50a69 100644
--- a/rhel/openvswitch-fedora.spec.in
+++ b/rhel/openvswitch-fedora.spec.in
@@ -228,6 +228,7 @@ make -f %{_datadir}/selinux/devel/Makefile
 %install
 rm -rf $RPM_BUILD_ROOT
 make install DESTDIR=$RPM_BUILD_ROOT
+find $RPM_BUILD_ROOT -name 'ovs-test*'
 
 install -d -m 0755 $RPM_BUILD_ROOT%{_sysconfdir}/openvswitch
 
to find out whether the ovs-test manpage is being installed at all and
if so where.
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-24 Thread Leif Madsen 
On Mon, Apr 24, 2017 at 3:57 PM, Ben Pfaff  wrote:

> On Mon, Apr 24, 2017 at 03:52:53PM -0400, Leif Madsen wrote:
> > I think this change might have broken packaging :)
> >
> > I just tested, and with the removal / renaming of the man8 pages for
> > ovs-test and ovs-vlan-test, the RPM fails to build because of missing
> files
> > that no longer match the glob.
> >
> > These two lines need to be removed from the build:
> >
> > 471 %{_mandir}/man8/ovs-test.8*
> > 472 %{_mandir}/man8/ovs-vlan-test.8*
> >
> >
> > I'll submit a patch shortly.
>
> OK, I'm confused then.  There was no removal or renaming of the
> installed man8 pages, only of the source files.  So, when I run "make
> install DESTDIR=$PWD/inst", I get a file
> inst/usr/share/man/man8/ovs-test.8 installed, and that should be the
> same as before.
>
> Any idea what's going on?
>

Huh, well then I'm very confused as well :)

I just did a test, and things seem to build fine when I remove those two
lines. Otherwise, the RPM will fail to build with the following:

Processing files:
openvswitch-test-2.7.90.14191.git3570f7e4-1.el7.centos.noarch
error: File not found by glob:
/builddir/build/BUILDROOT/openvswitch-2.7.90.14191.git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-test.8*
error: File not found by glob:
/builddir/build/BUILDROOT/openvswitch-2.7.90.14191.git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-vlan-test.8*


RPM build errors:
File not found by glob:
/builddir/build/BUILDROOT/openvswitch-2.7.90.14191.git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-test.8*
File not found by glob:
/builddir/build/BUILDROOT/openvswitch-2.7.90.14191.git3570f7e4-1.el7.centos.x86_64/usr/share/man/man8/ovs-vlan-test.8*



So I'm not entirely sure why my build isn't resulting in those files. I
have everything being built from a script and done in mock, so things
should be quite reproducable. I see the same failure both on my COPR repo,
and in my local build environment.

Thoughts?

Leif.
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-24 Thread Ben Pfaff 
On Mon, Apr 24, 2017 at 03:52:53PM -0400, Leif Madsen wrote:
> I think this change might have broken packaging :)
> 
> I just tested, and with the removal / renaming of the man8 pages for
> ovs-test and ovs-vlan-test, the RPM fails to build because of missing files
> that no longer match the glob.
> 
> These two lines need to be removed from the build:
> 
> 471 %{_mandir}/man8/ovs-test.8*
> 
> 
> 
> 472 %{_mandir}/man8/ovs-vlan-test.8*
> 
> 
> I'll submit a patch shortly.

OK, I'm confused then.  There was no removal or renaming of the
installed man8 pages, only of the source files.  So, when I run "make
install DESTDIR=$PWD/inst", I get a file
inst/usr/share/man/man8/ovs-test.8 installed, and that should be the
same as before.

Any idea what's going on?

Thanks,

Ben.
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-24 Thread Leif Madsen 
I think this change might have broken packaging :)

I just tested, and with the removal / renaming of the man8 pages for
ovs-test and ovs-vlan-test, the RPM fails to build because of missing files
that no longer match the glob.

These two lines need to be removed from the build:

471 %{_mandir}/man8/ovs-test.8*



472 %{_mandir}/man8/ovs-vlan-test.8*


I'll submit a patch shortly.

Thanks,
Leif.

On Fri, Apr 14, 2017 at 4:18 PM, Ben Pfaff  wrote:

> I understand now.
>
> I think that this change should be invisible to the Debian and RHEL
> packaging, because both kinds of packaging use "make install
> DESTDIR=..." to install the manpages into a staging tree, then package
> them from that staging tree.  With this change, "make install" behaves
> the same way as before: both before and after the change, "make install"
> puts nroff versions of the manpages into $(DESTDIR)/usr/share/man/man#/
> (or wherever they are configured to go).
>
> (I have not actually tested either kind of packaging.)


-- 
Leif Madsen | Partner Engineer - NFV & CI
NFV Partner Engineering
Red Hat
GPG: (D670F846) BEE0 336E 5406 42BA 6194 6831 B38A 291E D670 F846
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-14 Thread Ben Pfaff 
On Fri, Apr 14, 2017 at 09:00:49PM +0100, Stephen Finucane wrote:
> On Fri, 2017-04-14 at 12:49 -0700, Ben Pfaff wrote:
> > On Fri, Apr 14, 2017 at 06:55:38PM +0100, Stephen Finucane wrote:
> > > On Thu, 2017-04-13 at 21:27 -0700, Ben Pfaff wrote:
> > > > Thank you!  rST is much more readable than nroff.  I have some
> > > > comments
> > > > below.
> > > > 
> > > > On Mon, Apr 10, 2017 at 01:12:28PM +0100, Stephen Finucane wrote:
> > > > > Let's start with a simple one that lets us focus on setting up
> > > > > most
> > > > > of the required "infrastructure" for building man pages using
> > > > > Sphinx.
> > > > > 
> > > > > There are a couple of things worth noting here:
> > > > > 
> > > > > - The 'check-htmldocs' target becomes 'check-docs' as its now
> > > > >   responsible for building man page docs too.
> > > > > 
> > > > > - The outputted file will always have a '.1' suffix. This is 
> > > > > Sphinx's
> > > > >   decision, and likely stems from the man page guidelines [1]
> > > > > which
> > > > >   state that "the name of the man page's source file...is the
> > > > > name
> > > > > of
> > > > >   the command, function or file name, followed by a dot,
> > > > > followed
> > > > > by the
> > > > >   section character".
> > > > 
> > > > It looks to me like the last element of the tuples inside
> > > > man_pages
> > > > in conf.py controls the section.  When I changed 1 to 8 there, it
> > > > switched the manpage to section 8.  So I made that change in
> > > > conf.py
> > > > and I removed the above paragraph from the commit message.
> > > > 
> > > > > Other than that, hurrah for (mostly) legible syntaxes.
> > > > > 
> > > > > [1] http://www.tldp.org/HOWTO/Man-Page/q2.html
> > > > > 
> > > > > Signed-off-by: Stephen Finucane 
> > > > > ---
> > > > > I don't know if this is correctly integrated into the docs
> > > > > build
> > > > > system or not. I need someone to double check this for me. In
> > > > > particular, I think I need to integrate the 'dh_sphinxdoc'
> > > > > package
> > > > > [2] into the Debian build but I've no idea how to.
> > > > > 
> > > > > [2] http://manpages.ubuntu.com/manpages/zesty/man1/dh_sphinxdoc
> > > > > .1.h
> > > > > tml
> > > > 
> > > > I spent a couple of hours working on the build and install system
> > > > here.
> > > > 
> > > > My first thought was to add rules to allow Automake to find and
> > > > install the generated manpages.  This turned out to be a huge
> > > > mess
> > > > that required tons of nasty GNU Make specific crap in the
> > > > makefiles,
> > > > and I didn't like it.
> > > > 
> > > > My second approach was better.  I gave up on integrating with the
> > > > builtin Automake rules for manpages.  All those really do anyway
> > > > is
> > > > handle install and uninstall, so I wrote some Make rules to do
> > > > that.
> > > > They're ugly because they're make+shell, but readable enough if
> > > > you
> > > > squint.
> > > > 
> > > > The main question for install and uninstall is how to choose the
> > > > right section.  The easiest way seems to be to give the .rst
> > > > files
> > > > names that embed the section, like "ovs-vlan-test.8.rst".  This
> > > > is
> > > > also handy to distinguish manpages with the same name but in
> > > > different sections, which is sometimes a reasonable thing to
> > > > have, so
> > > > that's what I did.
> > > 
> > > I still need to have a look into the patch (anything to do with
> > > autotools is generally worth avoiding, heh), but I had a crazy idea
> > > over the weekend: couldn't we just include the compiled man pages
> > > in
> > > the source? The only issue with this would be the '.TH' line, but
> > > there
> > > are solutions for avoiding this [1][2]. If we have man pages
> > > included
> > > in the source, would that be adequate to use the standard autotools
> > > setup for manpages?
> > 
> > I might not understand this idea yet.  Do you mean, to include the
> > nroff output of sphinx in the Git repository?  I don't know why this
> > would help.
> 
> Correct.
> 
> > I'm not sure there are any serious disadvantages to writing Make
> > rules to install and uninstall manpages.
> 
> The only significant advantage would be simplicity for use in other
> build systems. Would the rules you've proposed work for the Debian and
> RHEL packaging, for example?

I understand now.

I think that this change should be invisible to the Debian and RHEL
packaging, because both kinds of packaging use "make install
DESTDIR=..." to install the manpages into a staging tree, then package
them from that staging tree.  With this change, "make install" behaves
the same way as before: both before and after the change, "make install"
puts nroff versions of the manpages into $(DESTDIR)/usr/share/man/man#/
(or wherever they are configured to go).

(I have not actually tested either kind of packaging.)
___
dev mailing list
d...@openvswitch.org

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-14 Thread Stephen Finucane 
On Fri, 2017-04-14 at 12:49 -0700, Ben Pfaff wrote:
> On Fri, Apr 14, 2017 at 06:55:38PM +0100, Stephen Finucane wrote:
> > On Thu, 2017-04-13 at 21:27 -0700, Ben Pfaff wrote:
> > > Thank you!  rST is much more readable than nroff.  I have some
> > > comments
> > > below.
> > > 
> > > On Mon, Apr 10, 2017 at 01:12:28PM +0100, Stephen Finucane wrote:
> > > > Let's start with a simple one that lets us focus on setting up
> > > > most
> > > > of the required "infrastructure" for building man pages using
> > > > Sphinx.
> > > > 
> > > > There are a couple of things worth noting here:
> > > > 
> > > > - The 'check-htmldocs' target becomes 'check-docs' as its now
> > > >   responsible for building man page docs too.
> > > > 
> > > > - The outputted file will always have a '.1' suffix. This is 
> > > > Sphinx's
> > > >   decision, and likely stems from the man page guidelines [1]
> > > > which
> > > >   state that "the name of the man page's source file...is the
> > > > name
> > > > of
> > > >   the command, function or file name, followed by a dot,
> > > > followed
> > > > by the
> > > >   section character".
> > > 
> > > It looks to me like the last element of the tuples inside
> > > man_pages
> > > in conf.py controls the section.  When I changed 1 to 8 there, it
> > > switched the manpage to section 8.  So I made that change in
> > > conf.py
> > > and I removed the above paragraph from the commit message.
> > > 
> > > > Other than that, hurrah for (mostly) legible syntaxes.
> > > > 
> > > > [1] http://www.tldp.org/HOWTO/Man-Page/q2.html
> > > > 
> > > > Signed-off-by: Stephen Finucane 
> > > > ---
> > > > I don't know if this is correctly integrated into the docs
> > > > build
> > > > system or not. I need someone to double check this for me. In
> > > > particular, I think I need to integrate the 'dh_sphinxdoc'
> > > > package
> > > > [2] into the Debian build but I've no idea how to.
> > > > 
> > > > [2] http://manpages.ubuntu.com/manpages/zesty/man1/dh_sphinxdoc
> > > > .1.h
> > > > tml
> > > 
> > > I spent a couple of hours working on the build and install system
> > > here.
> > > 
> > > My first thought was to add rules to allow Automake to find and
> > > install the generated manpages.  This turned out to be a huge
> > > mess
> > > that required tons of nasty GNU Make specific crap in the
> > > makefiles,
> > > and I didn't like it.
> > > 
> > > My second approach was better.  I gave up on integrating with the
> > > builtin Automake rules for manpages.  All those really do anyway
> > > is
> > > handle install and uninstall, so I wrote some Make rules to do
> > > that.
> > > They're ugly because they're make+shell, but readable enough if
> > > you
> > > squint.
> > > 
> > > The main question for install and uninstall is how to choose the
> > > right section.  The easiest way seems to be to give the .rst
> > > files
> > > names that embed the section, like "ovs-vlan-test.8.rst".  This
> > > is
> > > also handy to distinguish manpages with the same name but in
> > > different sections, which is sometimes a reasonable thing to
> > > have, so
> > > that's what I did.
> > 
> > I still need to have a look into the patch (anything to do with
> > autotools is generally worth avoiding, heh), but I had a crazy idea
> > over the weekend: couldn't we just include the compiled man pages
> > in
> > the source? The only issue with this would be the '.TH' line, but
> > there
> > are solutions for avoiding this [1][2]. If we have man pages
> > included
> > in the source, would that be adequate to use the standard autotools
> > setup for manpages?
> 
> I might not understand this idea yet.  Do you mean, to include the
> nroff output of sphinx in the Git repository?  I don't know why this
> would help.

Correct.

> I'm not sure there are any serious disadvantages to writing Make
> rules to install and uninstall manpages.

The only significant advantage would be simplicity for use in other
build systems. Would the rules you've proposed work for the Debian and
RHEL packaging, for example?

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-14 Thread Ben Pfaff 
On Fri, Apr 14, 2017 at 06:55:38PM +0100, Stephen Finucane wrote:
> On Thu, 2017-04-13 at 21:27 -0700, Ben Pfaff wrote:
> > Thank you!  rST is much more readable than nroff.  I have some
> > comments
> > below.
> > 
> > On Mon, Apr 10, 2017 at 01:12:28PM +0100, Stephen Finucane wrote:
> > > Let's start with a simple one that lets us focus on setting up most
> > > of the required "infrastructure" for building man pages using
> > > Sphinx.
> > > 
> > > There are a couple of things worth noting here:
> > > 
> > > - The 'check-htmldocs' target becomes 'check-docs' as its now
> > >   responsible for building man page docs too.
> > > 
> > > - The outputted file will always have a '.1' suffix. This is 
> > > Sphinx's
> > >   decision, and likely stems from the man page guidelines [1] which
> > >   state that "the name of the man page's source file...is the name
> > > of
> > >   the command, function or file name, followed by a dot, followed
> > > by the
> > >   section character".
> > 
> > It looks to me like the last element of the tuples inside man_pages
> > in conf.py controls the section.  When I changed 1 to 8 there, it
> > switched the manpage to section 8.  So I made that change in conf.py
> > and I removed the above paragraph from the commit message.
> > 
> > > Other than that, hurrah for (mostly) legible syntaxes.
> > > 
> > > [1] http://www.tldp.org/HOWTO/Man-Page/q2.html
> > > 
> > > Signed-off-by: Stephen Finucane 
> > > ---
> > > I don't know if this is correctly integrated into the docs build
> > > system or not. I need someone to double check this for me. In
> > > particular, I think I need to integrate the 'dh_sphinxdoc' package
> > > [2] into the Debian build but I've no idea how to.
> > > 
> > > [2] http://manpages.ubuntu.com/manpages/zesty/man1/dh_sphinxdoc.1.h
> > > tml
> > 
> > I spent a couple of hours working on the build and install system
> > here.
> > 
> > My first thought was to add rules to allow Automake to find and
> > install the generated manpages.  This turned out to be a huge mess
> > that required tons of nasty GNU Make specific crap in the makefiles,
> > and I didn't like it.
> > 
> > My second approach was better.  I gave up on integrating with the
> > builtin Automake rules for manpages.  All those really do anyway is
> > handle install and uninstall, so I wrote some Make rules to do that.
> > They're ugly because they're make+shell, but readable enough if you
> > squint.
> > 
> > The main question for install and uninstall is how to choose the
> > right section.  The easiest way seems to be to give the .rst files
> > names that embed the section, like "ovs-vlan-test.8.rst".  This is
> > also handy to distinguish manpages with the same name but in
> > different sections, which is sometimes a reasonable thing to have, so
> > that's what I did.
> 
> I still need to have a look into the patch (anything to do with
> autotools is generally worth avoiding, heh), but I had a crazy idea
> over the weekend: couldn't we just include the compiled man pages in
> the source? The only issue with this would be the '.TH' line, but there
> are solutions for avoiding this [1][2]. If we have man pages included
> in the source, would that be adequate to use the standard autotools
> setup for manpages?

I might not understand this idea yet.  Do you mean, to include the
nroff output of sphinx in the Git repository?  I don't know why this
would help.

I'm not sure there are any serious disadvantages to writing Make rules
to install and uninstall manpages.
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-14 Thread Stephen Finucane 
On Thu, 2017-04-13 at 21:27 -0700, Ben Pfaff wrote:
> Thank you!  rST is much more readable than nroff.  I have some
> comments
> below.
> 
> On Mon, Apr 10, 2017 at 01:12:28PM +0100, Stephen Finucane wrote:
> > Let's start with a simple one that lets us focus on setting up most
> > of the required "infrastructure" for building man pages using
> > Sphinx.
> > 
> > There are a couple of things worth noting here:
> > 
> > - The 'check-htmldocs' target becomes 'check-docs' as its now
> >   responsible for building man page docs too.
> > 
> > - The outputted file will always have a '.1' suffix. This is 
> > Sphinx's
> >   decision, and likely stems from the man page guidelines [1] which
> >   state that "the name of the man page's source file...is the name
> > of
> >   the command, function or file name, followed by a dot, followed
> > by the
> >   section character".
> 
> It looks to me like the last element of the tuples inside man_pages
> in conf.py controls the section.  When I changed 1 to 8 there, it
> switched the manpage to section 8.  So I made that change in conf.py
> and I removed the above paragraph from the commit message.
> 
> > Other than that, hurrah for (mostly) legible syntaxes.
> > 
> > [1] http://www.tldp.org/HOWTO/Man-Page/q2.html
> > 
> > Signed-off-by: Stephen Finucane 
> > ---
> > I don't know if this is correctly integrated into the docs build
> > system or not. I need someone to double check this for me. In
> > particular, I think I need to integrate the 'dh_sphinxdoc' package
> > [2] into the Debian build but I've no idea how to.
> > 
> > [2] http://manpages.ubuntu.com/manpages/zesty/man1/dh_sphinxdoc.1.h
> > tml
> 
> I spent a couple of hours working on the build and install system
> here.
> 
> My first thought was to add rules to allow Automake to find and
> install the generated manpages.  This turned out to be a huge mess
> that required tons of nasty GNU Make specific crap in the makefiles,
> and I didn't like it.
> 
> My second approach was better.  I gave up on integrating with the
> builtin Automake rules for manpages.  All those really do anyway is
> handle install and uninstall, so I wrote some Make rules to do that.
> They're ugly because they're make+shell, but readable enough if you
> squint.
> 
> The main question for install and uninstall is how to choose the
> right section.  The easiest way seems to be to give the .rst files
> names that embed the section, like "ovs-vlan-test.8.rst".  This is
> also handy to distinguish manpages with the same name but in
> different sections, which is sometimes a reasonable thing to have, so
> that's what I did.

I still need to have a look into the patch (anything to do with
autotools is generally worth avoiding, heh), but I had a crazy idea
over the weekend: couldn't we just include the compiled man pages in
the source? The only issue with this would be the '.TH' line, but there
are solutions for avoiding this [1][2]. If we have man pages included
in the source, would that be adequate to use the standard autotools
setup for manpages?

> The patch didn't delete the old manpage, so I did that too.
> 
> I noticed that the "Synposis" section of the new ovs-vlan-test.rst
> did not use bold and italic in the canonical way for manpages, so I
> added * and ** in the right places.

++

Stephen

[1] https://gitlab.labs.nic.cz/labs/knot/blob/bab62de/doc/Makefile.am#L
149-158
[2] https://gitlab.labs.nic.cz/labs/knot/blob/bab62de/doc/man/kdig.1in
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

2017-04-13 Thread Ben Pfaff 
Thank you!  rST is much more readable than nroff.  I have some comments
below.

On Mon, Apr 10, 2017 at 01:12:28PM +0100, Stephen Finucane wrote:
> Let's start with a simple one that lets us focus on setting up most of
> the required "infrastructure" for building man pages using Sphinx.
> 
> There are a couple of things worth noting here:
> 
> - The 'check-htmldocs' target becomes 'check-docs' as its now
>   responsible for building man page docs too.
> 
> - The outputted file will always have a '.1' suffix. This is Sphinx's
>   decision, and likely stems from the man page guidelines [1] which
>   state that "the name of the man page's source file...is the name of
>   the command, function or file name, followed by a dot, followed by the
>   section character".

It looks to me like the last element of the tuples inside man_pages in
conf.py controls the section.  When I changed 1 to 8 there, it switched
the manpage to section 8.  So I made that change in conf.py and I
removed the above paragraph from the commit message.

> Other than that, hurrah for (mostly) legible syntaxes.
> 
> [1] http://www.tldp.org/HOWTO/Man-Page/q2.html
> 
> Signed-off-by: Stephen Finucane 
> ---
> I don't know if this is correctly integrated into the docs build system
> or not. I need someone to double check this for me. In particular, I
> think I need to integrate the 'dh_sphinxdoc' package [2] into the Debian
> build but I've no idea how to.
> 
> [2] http://manpages.ubuntu.com/manpages/zesty/man1/dh_sphinxdoc.1.html

I spent a couple of hours working on the build and install system here.

My first thought was to add rules to allow Automake to find and install
the generated manpages.  This turned out to be a huge mess that required
tons of nasty GNU Make specific crap in the makefiles, and I didn't like
it.

My second approach was better.  I gave up on integrating with the
builtin Automake rules for manpages.  All those really do anyway is
handle install and uninstall, so I wrote some Make rules to do that.
They're ugly because they're make+shell, but readable enough if you
squint.

The main question for install and uninstall is how to choose the right
section.  The easiest way seems to be to give the .rst files names that
embed the section, like "ovs-vlan-test.8.rst".  This is also handy to
distinguish manpages with the same name but in different sections, which
is sometimes a reasonable thing to have, so that's what I did.

The patch didn't delete the old manpage, so I did that too.

I noticed that the "Synposis" section of the new ovs-vlan-test.rst did
not use bold and italic in the canonical way for manpages, so I added *
and ** in the right places.
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev