Re: man2html

Hi Alec,

On Jan 02 19:07:39, [email protected] wrote:
> >>> On Jan 1, 2018, at 6:40 PM, Jan Stary <[email protected]> wrote:
> >>> I would like to remove man2htl from macports.
> >>> I see that liirc (which you maintain) requires it
> >>> as a build dependency. Why exactly is it required please?
> > 
> > On Jan 01 21:00:03, ctreleaven-/[email protected] wrote:
> >> lirc provides extensive documentation in html format
> >> and uses man2html to produce some of it.
> > 
> > it seems to produce the html manpages (the API html documentation
> > is produced differently). For example, as there is irexec(1), i.e.
> > /opt/local/share/man/man1/irexec.1.gz, there is also
> > /opt/local/share/doc/lirc/lirc.org/html/irexec.html
> > - but this is what it says (viewing with lynx):'
> 
> [bad html]
> 
> > That's not a html version of irexec(1), that's a failed run of man2html.
> > Apparently, no-one hasn't looked at the html manpages; it doesn't work.
> 
> Strange thing is that by me (fedora 26, lirc devel branch) there is
> nothing wrong with irexec.html. So it seems thatl your environment is
> part of this. Fedora's man2html version is 1.6-18. What's yours?

There is a bout ten things out there that call thamselves 'man2html'.
LIRC's build system seems to expect a particular one (with -M and -r).

The two versions of 'man2html' I have tried is the one that comes
with the 'man2html' port in MacPorts (does not work), and the one
that comes with the 'man' port in MacPorts (does work).

https://github.com/macports/macports-ports/tree/master/textproc/man2html
https://github.com/macports/macports-ports/tree/master/sysutils/man

> > We have the original manpages in the first place;
> > why produce a boken html version?
> 
> Because part of the build is to produce the website, and the html
> manpages is an integrated part of this. We don't really have the
> manpower to rewrite all these docs :(

That's my main point: why do you include html versions of the manpages
in the manual at all? Any user can just run 'man irexec' and read the
original actual manpage (and it's the version he installed,
not the online webpage version possibly a release ahead etc).

> > Can we drop this entirely please?
> 
> So, not really...
> 
> > I am willing to do the work (with the intent
> > of eventually removing man2html from the ports).
> 
> Isn't this basically a downstream packaging issue?

Yes it is: the particular failure here happens in MacPorts,
which is a packaging system for MacOS, where Craig Treleaven
maintains the port of LIRC. Apparently, it's been using the
wrong 'man2html' to build the html manpages.
https://github.com/macports/macports-ports/pull/1189

And no it's not: AFAICT, LIRC's ./configure never cares
whether the 'man2html' binary it has found is the one it expects.
If it's the not the right one, then e.g.

src=$(echo ./man-html/irexec.html | /opt/local/bin/gsed -e 's/man-html/man/' -e 's/\.html//'); \
	    man2html -M index.html -r ${src}.[1-8] | \
		/opt/local/bin/gsed \
	            -e '1,/^$/d' \
		    -e '/This document was created/i \
                        <p>'  \
		    -e '/^Time:/a \
                        </p>'  \
		    -e '/HREF/s|".*man[1-9]/\(.*\)[0-9]\.html|"\1html|' | \
			 xsltproc --html ./manpage.xsl - | \
			    /opt/local/bin/gsed -e '/href="\.\.\/index.html"/s|\.\./||' > man-html/irexec.html
Unknown option: m
Unknown option: r

Apparently, the 'man2html' that comes with your Fedora
is one that works with LIRC's build system expects;
other version are not, but ./configure never cares:

	AM_CONDITIONAL(HAVE_MAN2HTML, test x$MAN2HTML = xyes)

If a 'man2html' was found (any one), run it. Never mind whether
it has a -M or -r option, or whether the command failed or not.
And if it was not found, just let the manual be broken.

> From upstream perspective: could you please file a bug,
> so we can handle it properly?
> (bugs are easier to track)

I will.

> Note that man2html is *not* distributed with lirc it's a build dependency.

Yes.

> IIRC, it's possible to build without it. If not, it shouldn't be that
> hard to fix the autotools setup so it works. Looking at configure.ac the
> mechanisms to handle a missing man2html is already in place. I doubt
> it's heavily tested, but again IIRC it at least has worked at some
> point. Perhaps this is the way to handle this problem?

IMHO the clean solution would be to let manpages be manpages,
as opposed to subsections in a html book, and be done with it
- the problem disappears. Even if autoconf/configure finds
a 'man2html', it still does not know it will produce the
html manpages that Chapter 4 consists of, and it never checks.

	Jan


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot