From: Craig T. <ctr...@ma...> - 2018-01-02 02:34:27
|
Hi Jan: lirc provides extensive documentation in html format and uses man2html to produce some of it. Is there some other tool that replaces man2html that I should be using? Craig > On Jan 1, 2018, at 6:40 PM, Jan Stary <ha...@st...> wrote: > > Hello Craig, > > 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? > > Thank you > > Jan > > > |
From: Jan S. <ha...@st...> - 2018-01-02 10:34:11
|
Hi Craig, > > On Jan 1, 2018, at 6:40 PM, Jan Stary <ha...@st...> 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, ctr...@ma... 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): LIRC icon LIRC logo Description: man2html takes formatted manpages from STDIN and converts it to HTML sent to STDOUT. The -topm and -botm arguments are the number of lines to the main body text and NOT to the running headers/footers. Version: 3.0.1 Copyright (C) 1995-1997 Earl Hood, eh...@me... man2html comes with ABSOLUTELY NO WARRANTY and man2html may be copied only under the terms of the GNU General Public License, which may be found in the man2html distribution. [[1]LIRC homepage] 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. We have the original manpages in the first place; why produce a boken html version? Can we drop this entirely please? I am willing to do the work (with the intent of eventually removing man2html from the ports). > Is there some other tool that replaces man2html that I should be using? There is groff -man -Thtml in the base system. The output is not very nice, but still superior to man2html. Try 'man2html /usr/share/man/man1/ls.1' vs 'groff -man -Thtml /usr/share/man/man1/ls.1' - it even lacks the NAME entry. There is also a newer groff in ports; and there is mandoc, whose 'mandoc -Thtml' output is way superior to them both. But as I said, can we please drop generating the html pages entirely? Jan |
From: Alec L. <lea...@gm...> - 2018-01-02 18:07:51
|
Hi Jan! On 02/01/18 11:07, Jan Stary wrote: > Hi Craig, > >>> On Jan 1, 2018, at 6:40 PM, Jan Stary <ha...@st...> 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, ctr...@ma... 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? > 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 :( > 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? From upstream perspective: could you please file a bug, so we can handle it properly? (bugs are easier to track) Note that man2html is *not* distributed with lirc it's a build dependency. 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? Cheers! --alec |
From: Craig T. <ctr...@co...> - 2018-01-02 18:24:15
|
> On Jan 2, 2018, at 1:07 PM, Alec Leamas <lea...@gm...> wrote: > > Hi Jan! > > On 02/01/18 11:07, Jan Stary wrote: >> Hi Craig, >> >>>> On Jan 1, 2018, at 6:40 PM, Jan Stary <ha...@st...> 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, ctr...@ma... 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? > My bad there—for MacPorts, I should have used man2thml from the ‘man’ package. I never noticed the broken pages; just that the build errors had gone away. The packaging is now fixed. >> 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 :( > >> 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? From upstream > perspective: could you please file a bug, so we can handle it properly? > (bugs are easier to track) > > Note that man2html is *not* distributed with lirc it's a build dependency. > > 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? > Just using man2html from the man package fixes things sufficiently for my purposes. A number of projects have a configure switch that enables/disables developer documentation. Within MacPorts, we often have an install-time option to then include or exclude those docs (a “variant” in MacPorts-parlance). Personally, I would always want the regular man pages included in the package. Would it be a big project to make all the developer docs (including the html versions of the man pages) optional? Craig |
From: Jan S. <ha...@st...> - 2018-01-02 18:51:04
|
Hi Alec, On Jan 02 19:07:39, lea...@gm... wrote: > >>> On Jan 1, 2018, at 6:40 PM, Jan Stary <ha...@st...> 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, ctr...@ma... 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 |
From: Jan S. <ha...@st...> - 2018-01-02 20:23:59
|
> > From upstream perspective: could you please file a bug, > > so we can handle it properly? (bugs are easier to track) https://sourceforge.net/p/lirc/tickets/316/ Jan |
From: Jan S. <ha...@st...> - 2018-01-02 19:03:46
|
> Re lirc’s documentation, the current maintainer has recently done a lot of work to modernize the software. I kind of doubt that he will want to rip out the html docs since those get posted to the web site. That's what I find wrong: a html version of e.g. irexec on LIRC's webpage does not necessarily document the version of irexec I have on my machine; as opposed to `man irexec` which does. > As you note, lire installs both html and man versions > of the program documentation. On a local installation, that's particularly pointless. Why would I read (an ugly, broken-linked) irexec.html if I can read the original manpage? > But perhaps a configure switch could be added relatively easily > to suppress the dev documentation. > I would then make that a non-default variant of the port. If I understand correctly, there is the API documentation, produced by Doxygen straight to html; that's not related to this. Then there is the html LIRC manual, where Chapter 4 consists of the html versions of the manpages, converted by man2html. Such a ./configure switch would need to determine how to build the manual, in particular, whether to include Chapter 4. That's needless complexity I think. Just let manpages be manpages. Jan |
From: Jan S. <ha...@st...> - 2018-01-02 19:09:47
|
> Just using man2html from the man package > fixes things sufficiently for my purposes. Yes it does - in MacPorts, which now uses this particular man2html. There are many other man2html's out there (all as shit as this one), so it's entirely possible this same thing is broken on other systems. > A number of projects have a configure switch that enables/disables > developer documentation. A manpage for the binaries is not developer documentation, it's user documentation. A description of the API is developer documentation, adn I get it rght, that's currently built with Doxygen, not related the the man2html problem (right?). > Within MacPorts, we often have an install-time option to then include or exclude those docs (a “variant” in MacPorts-parlance). Personally, I would always want the regular man pages included in the package. Of course. > Would it be a big project to make all the developer docs > (including the html versions of the man pages) optional? I believe it would be beneficial to have a default variant that does not install the API docs and the html manual (and whuch does not need doxygen and man and perhaps other stuff), and a 'doc' variant (is there a prefferred name for such variants?) taht would also install the API docs and the html manual. (But that's a MacPorts question of course, not relaed to LIRC itself). Jan |
From: Bengt M. <bu...@be...> - 2018-01-02 20:16:21
|
I would like to add my 2 cents here The idea of portable, single-source documentation (source of the documentation in a content-oriented format, then processors producing different target formats) is modern, well established practice, not only in Linux community. For example, already the Gnu project decided on such a system (texinfo). This is a very good and clean approach. Among other things, we can achieve a separation between form and content. This is not to say that the present system is perfect, or even good. The fact that there are minor problems with one of the post-processors (man2html) is not justification to throw out the principle of portable documentation. Moreover, the man format is _very_ legacy, coming from the early 1970-ties (?). (So the GNU project decided to invent something better, and wrote man pages just as stubs, essentially pointing to the texinfo docx.) On 01/02/18 20:09, Jan Stary wrote: >> Just using man2html from the man package >> fixes things sufficiently for my purposes. > > Yes it does - in MacPorts, which now uses this particular man2html. > There are many other man2html's out there (all as shit as this one), > so it's entirely possible this same thing is broken on other systems. I see you point (although I would prefer a less fecal language...). So the only really portable solution would be to pack some portable implementation (for example in Python3) in the package; should not be too hard. Wanna help? > A manpage for the binaries is not developer documentation, > it's user documentation. A description of the API is developer > documentation, adn I get it rght, that's currently built > with Doxygen, not related the the man2html problem (right?). Right. (It is also likely identical upstreams and downstreams.) So lets leave out the API docx from the discussion. >> Would it be a big project to make all the developer docs >> (including the html versions of the man pages) optional? > > I believe it would be beneficial to have a default variant > that does not install the API docs and the html manual > (and whuch does not need doxygen and man and perhaps other stuff), > and a 'doc' variant (is there a prefferred name for such variants?) > taht would also install the API docs and the html manual. > > (But that's a MacPorts question of course, > not relaed to LIRC itself). The question makes sense also "upstreams". It is basically a question of implementing it. I am sure the maintainer would be happy for pull requests and will merge all that are sensible. (BTW, make targets are better than configuration options.) Greetz, Bengt |
From: Jan S. <ha...@st...> - 2018-01-02 20:42:09
|
On Jan 02 21:11:03, bu...@be... wrote: > The idea of portable, single-source documentation (source of the > documentation in a content-oriented format, then processors producing > different target formats) is modern, well established practice, not only in > Linux community. For example, already the Gnu project decided on such a > system (texinfo). This is a very good and clean approach. Among other > things, we can achieve a separation between form and content. A manpage is a single-source documentation, and groff's (or heirloom's or mandoc's ...) rendering of it via -man -T(ascii|html|ps|pdf) are the different target formats. What other formats are there to be desired? Also, being a GNU decision does not mean to be "well-established". (BTW, ESR and RMS agree to move from texinfo to asciidoc or whichaver GNU attrocity du jour.) > This is not to say that the present system is perfect, or even good. > The fact that there are minor problems with one of the post-processors > (man2html) is not justification to throw out the principle of portable > documentation. A single manpage is portable documentation. It has been for decades. Relying on a particular tool to transpose it in a particular way is not. > Moreover, the man format is _very_ legacy, coming from the early 1970-ties. Yes, just like UNIX. Proper manpages are written in the mdoc(7) language, not man(7). The *BSDs have made the switch years ago, MacOS more recently. > (So the GNU project decided to invent something better, and wrote man > pages just as stubs, essentially pointing to the texinfo docx.) That's one of the GNU attrocities: "manpages are stubs". They are not - they are the ultimate documentation. > On 01/02/18 20:09, Jan Stary wrote: > > > Just using man2html from the man package > > > fixes things sufficiently for my purposes. > > > > Yes it does - in MacPorts, which now uses this particular man2html. > > There are many other man2html's out there (all as shit as this one), > > so it's entirely possible this same thing is broken on other systems. > > I see you point (although I would prefer a less fecal language...). Have you seen its output, even in the case when it works? > So the > only really portable solution would be to pack some portable implementation > (for example in Python3) in the package; should not be too hard. Wanna help? My motivation here is to get rid of man2html in the MacPorts, which is what got me here, realizing the are about ten "man2html"s. Creating a Python3 translator from man to html is quite the opposite of where I come from. Also, having just the manpages and not their html transalations, that would be totally portable. Jan |
From: Alec L. <lea...@gm...> - 2018-01-02 20:53:32
|
On 02/01/18 21:42, Jan Stary wrote: > On Jan 02 21:11:03, bu...@be... wrote: > Also, having just the manpages and not their html transalations, > that would be totally portable. Besides possible bugs, lirc is actually supposed to build without man2html available and in this case don't build the html manpages. Portable enough, isn't it? Cheers! --alec |
From: Jan S. <ha...@st...> - 2018-01-02 21:01:46
|
On Jan 02 21:53:23, lea...@gm... wrote: > > > On 02/01/18 21:42, Jan Stary wrote: > > On Jan 02 21:11:03, bu...@be... wrote: > > > > Also, having just the manpages and not their html transalations, > > that would be totally portable. > > Besides possible bugs, lirc is actually supposed to build without > man2html available and in this case don't build the html manpages. > Portable enough, isn't it? Yes. What I'm saying is don't build the html manpages in any case: there is no added value in it, just technical problems like this one (Is it a good man2html? Does it have an -M doing what I think it does?) Jan |
From: Alec L. <lea...@gm...> - 2018-01-02 21:12:56
|
On 02/01/18 22:01, Jan Stary wrote: > > Yes. What I'm saying is don't build the html manpages in any case: > there is no added value in it, just technical problems like this one > (Is it a good man2html? Does it have an -M doing what I think it does?) > It's not that simple. The html manpgaes are an integrated part of the website, and the website is built as part of the build. Overall, this is a Good Thing which keeps things in sync. That said, it should be possible for downstreams such as MacPort to disable this. For now, this is a bit clumsy, depending on a probe for man2html to fail. Given this discussion, a handle to disable this explicitly makes sense. Let's discuss in the bug. --alec |