Hi Eric, while i appreciate your intention to get rid of info(1), what you are proposing here looks like throwing the baby out with the bathwater...
Eric S. Raymond wrote on Fri, Feb 28, 2014 at 12:15:35PM -0500: > Where we're probably going is that (a) info will die, to be replaced > by HTML browsed from within Emacs, and That's two bad ideas in half a sentence. Most free software is also portable software. Emacs is restrictively licensed (GPL), so you cannot assume it is available on the systems where the software will be used. Even systems that support installing emacs as an add-on cannot use it for manual display because manual display has to be part of the base system, not something dependent on third-party add-on software. And you are certainly aware that distributing system documentation as HTML will meet strong resistance in many communities. In some because they consider HTML as overkill for manuals, in others - like the groff community - because typesetting quality resulting from it is inferior. This has just been discussed here. > (b) Texinfo will be replaced by a modern lightweight format that > can render to both print and HTML; most likely asciidoc. That's another really terrible idea. The asciidoc package is not lightweight at all, it depends on docbook-xsl and python. Besides, it's about the slowest documentation formatting system i'm currently aware of. It is so slow that its use can cause serious increases of build times in ported software builds. Often, merely formatting documentation with asciidoc consumes build times of comparable order of magnitude needed for compiling the software itself. It is much, much slower than groff for formatting manuals (and note that while groff is a really fast typesetting system, it is relatively slow when used as a mere manual formatter). So, many systems will continue to require man(7) or mdoc(7) manuals for installation. With pushing portable software authors towards using asciidoc(1), you are doing the world a very serious disservice, because among all automatic man(7) code generators i'm aware of, DocBook has by far the poorest output quality, so by all means, we should try to push people *away* from asciidoc, not towards it. Fortunately, what you are campaigning for is not likely to happen. Take the OpenBSD ports tree as an example. Currently, it contains 8743 software packages. Out of these, 16 use asciidoc; that's below 0.2%, and i hope it will stay like that. Even with this low number, i remember multiple complaints regarding the quality of these manuals, and multiple bogus mandoc bug reports that were actually asciidoc's or DocBook's fault, i.e. broken code generation. > Because the man-page stubs were a kludge to get around the complications of > browsing info outside of Emacs, I expect they'll quickly be perceived as > unnecessary after this transition and abolished in favor of Web pointers > to the real documentation. I doubt very much that is ever going to happen. Web pages are not a replacement for documentation installed on the local machine. I do want to have access to manuals of installed software when offline, and i certainly do not want links out of locally installed software documentation to point to the web. That would be much worse than pointing me at the locally installed info(1) utility, which will at least be available and document the actual version of the software if have. > 1. Jawbone all the world's man page authors into cleaning up their > markup so doclifter can interpret it structurally to clean XML and > (through that) HTML. I've been pretty successful at this: see > http://www.catb.org/~esr/doclifter/bugs.html for details and > statistics. > > 2. Some time ago I added to Linux man(1) the capability to recognize > HTML pages in the man hierachy and kick them over to the user's Web > browser. All Linux and *BSD distributions now ship this code. I'm not quite sure what you mean by Linux man(1); i failed to find your name here: http://git.savannah.gnu.org/cgit/man-db.git/log/ Anyway, i'm quite sure OpenBSD man(1) doesn't contain code you wrote, and a quick check of NetBSD, FreeBSD, and DragonFly didn't reveal anything, either. Note that FreeBSD man(1) is implemented in a different programming language than the three others. That already excludes code sharing. Besides, the functionality you propose here would almost certainly be rejected in the BSD communities, even if patches were sent. The man(1) utility is supposed to be fully functional without a browser. > Where I want us to be is that when users call man(1) the normal > behavior is to render through the browser. That is most definitely not going to happen in OpenBSD, and i would be very surprised if any other BSD would follow. Not all environments are running X, not all environments are fit for running a browser, but you want manuals everywhere. And i doubt that any people even *want* to see manuals in a browser. Very few people use PostScript or PDF viewers in some cases, but i never heard about anybody wanting manuals in their browser - even though it is easily feasible with current tools, just have man(1) write to a tempfile and call the browser on that, using the usual man.conf(5) or manpath(1) or whatever mechanisms. So, if you will ever start to push this, you are likely to end up with even worse fragmentation than we have now. Yours, Ingo
