I remember (but now can't find it) somebody commenting on the man file vs info documentation issue: that they disliked info because it doesn't reformat properly depending on window size.
Fedora (and GNU systems in general) should stop shipping info files, and should instead ship the texinfo source files. The makeinfo program will convert texinfo files into html or docbook, as well as old-fashioned info. Html or docbook is much nicer - you can use non-monospace fonts (for the body), and the text can be re-flowed to fit the window. Also, indexes and cross-references can take you to a precise location, rather than just a node.
An example of what you can do with texinfo: The Kawa home page at http://www.gnu.org/software/kawa/ is basically the Kawa texinfo manual, formatted to docbook using makeinfo, then formatted to HTML using the docbook-xslt stylesheets, with some extra shell-script hacking.
The info format is a obsolete legacy format designed for plain terminals. However, texinfo is a decent format - more compact and readable than (say) docbook. Texinfo is still actively maintained, with new features being added occasionally.
Info format should only be used for legacy programs that can only read info format: The standalone info program, and the emacs info mode. In both case, the info files should be generated on-the-fly as needed (and cached).
The user interface of the stand-alone info reader isn't bad - but better would be the info program's user interface (most importantly key-bindings) on top of a text-mode HTML browser such as lynx. In that case even the info program wouldn't use info files.
If so, instead of shipping texinfo, we might ship pre-formatted XHTML. (Emacs info mode would need to be able to handle such XHTML files, though.)
I doubt there is any important info documentation for which we can't get the texinfo source, so making this switch wouldn't lose any information.
On Thu, 2009-03-05 at 15:37 -0800, Per Bothner wrote:
Fedora (and GNU systems in general) should stop shipping info files, and should instead ship the texinfo source files. The makeinfo program will convert texinfo files into html or docbook, as well as old-fashioned info. Html or docbook is much nicer - you can use non-monospace fonts (for the body), and the text can be re-flowed to fit the window. Also, indexes and cross-references can take you to a precise location, rather than just a node.
Interesting idea. Is there any reason why this wouldn't work?
poc
PS I still want man pages all the same :-)
On Thu, 2009-03-05 at 23:36 -0430, Patrick O'Callaghan wrote:
On Thu, 2009-03-05 at 15:37 -0800, Per Bothner wrote:
Fedora (and GNU systems in general) should stop shipping info files, and should instead ship the texinfo source files. The makeinfo program will convert texinfo files into html or docbook, as well as old-fashioned info. Html or docbook is much nicer - you can use non-monospace fonts (for the body), and the text can be re-flowed to fit the window. Also, indexes and cross-references can take you to a precise location, rather than just a node.
Interesting idea. Is there any reason why this wouldn't work?
Are we then going to require people to use elinks or w3m to view them, plus expect them to know where the HTML pages are stored in the first place?
No, the far more sane option is to fix info or pinfo so that it catches SIGWINCH and reflows as necessary.
On Thu, 2009-03-05 at 15:37 -0800, Per Bothner wrote:
Fedora (and GNU systems in general) should stop shipping info files, and should instead ship the texinfo source files. The makeinfo program will convert texinfo files into html or docbook, as well as old-fashioned info. Html or docbook is much nicer - you can use non-monospace fonts (for the body), and the text can be re-flowed to fit the window. Also, indexes and cross-references can take you to a precise location, rather than just a node.
On Thu, 2009-03-05 at 23:36 -0430, Patrick O'Callaghan wrote:
Interesting idea. Is there any reason why this wouldn't work?
The main problem is someone needs to do the work and drive the process.
On 03/06/2009 12:26 AM, Ignacio Vazquez-Abrams wrote:
Are we then going to require people to use elinks or w3m to view them,
No. I guess I wasn't clear. I was suggesting that one possibility is to use elinks or w3m *automatically* as backends for the info program or info mode: Or rather the ideal would be a hybrid program that can display HTML files, but uses info keybindings and the info navigation paradigm.
plus expect them to know where the HTML pages are stored in the first place?
Do we require people to know where info pages or man pages are located? Of course not.
The proposal is: (1) Gnome/KDE help viewers and similar programs should not display pre-formatted info files, but instead either (a) format texinfo files on the fly, or (b) display pre-formatted html or docbook that have been generated from texinfo.
(2a) (Optionally) To avoid the redundancy of installing both texinfo and pre-formatted html or docbook one could save disk space by having info-reading programs cause the makeinfo program be invoked automatically as needed.
Alternatively:
(2b) Universally replace info format by xhtml, generated from makeinfo, and modify the info program and the emacs info mode to be able to read these xhtml files, possibly using elinks and w3m as a basis. But this is a larger project - I'd think focusing on (1) and maybe (2a) would be easier.
No, the far more sane option is to fix info or pinfo so that it catches SIGWINCH and reflows as necessary.
No, that's not feasible. The info file format just doesn't contain the necessary information: It's a more-or-less plain ASCII file, and doesn't distinguish between hard and soft linefeeds, for example. Plus you don't have the information needed to pick the correct fonts. Cross- references only identify a named node, rather than a specific paragraph. All of that information *is* in the texinfo source.
On Fri, 2009-03-06 at 01:03 -0800, Per Bothner wrote:
No, the far more sane option is to fix info or pinfo so that it catches SIGWINCH and reflows as necessary.
No, that's not feasible. The info file format just doesn't contain the necessary information: It's a more-or-less plain ASCII file, and doesn't distinguish between hard and soft linefeeds, for example. Plus you don't have the information needed to pick the correct fonts. Cross- references only identify a named node, rather than a specific paragraph. All of that information *is* in the texinfo source.
Fair enough.
The proposal is: (1) Gnome/KDE help viewers and similar programs should not display pre-formatted info files, but instead either (a) format texinfo files on the fly, or (b) display pre-formatted html or docbook that have been generated from texinfo.
(2a) (Optionally) To avoid the redundancy of installing both texinfo and pre-formatted html or docbook one could save disk space by having info-reading programs cause the makeinfo program be invoked automatically as needed.
Alternatively:
(2b) Universally replace info format by xhtml, generated from makeinfo, and modify the info program and the emacs info mode to be able to read these xhtml files, possibly using elinks and w3m as a basis. But this is a larger project - I'd think focusing on (1) and maybe (2a) would be easier.
Sounds good, but how much CPU does it take to convert texinfo into... something else? And does it need all of TeXlive in order to do it?
On 03/06/2009 03:01 AM, Ignacio Vazquez-Abrams wrote:
Sounds good, but how much CPU does it take to convert texinfo into... something else? And does it need all of TeXlive in order to do it?
TeXlive is only used to produce "printed" documentation: i.e. pdf files (or .dvi/.ps files in the old days).
To convert texinfo to info files or to html/xhtml./docbok you use the makeinfo program, which is a fairly fast C program abd doesn't any of the tex tools.
$ ls -l kawa.texi -rw-r--r--. 1 bothner bothner 286137 2009-02-06 17:34 kawa.texi $ time makeinfo -I . -o kawa.info kawa.texi real 0m0.163s user 0m0.134s sys 0m0.016s $ ls -l kawa.info* -rw-r--r--. 1 bothner bothner 2981 2009-03-06 08:17 kawa.info -rw-r--r--. 1 bothner bothner 281896 2009-03-06 08:17 kawa.info-1 -rw-r--r--. 1 bothner bothner 35188 2009-03-06 08:17 kawa.info-2
(The output is split into the above 3 files.)
On Fri, Mar 06, 2009 at 01:03:34AM -0800, Per Bothner wrote:
On 03/06/2009 12:26 AM, Ignacio Vazquez-Abrams wrote:
Are we then going to require people to use elinks or w3m to view them,
No. I guess I wasn't clear. I was suggesting that one possibility is to use elinks or w3m *automatically* as backends for the info program or info mode:
I hope that nobody will take that seriously. Search and navigation in html variants of documentation are between poor and non-existent. A search within just displayed fragment is not coming even close.
Michal
On 03/06/2009 07:54 AM, Michal Jaegermann wrote:
On Fri, Mar 06, 2009 at 01:03:34AM -0800, Per Bothner wrote:
On 03/06/2009 12:26 AM, Ignacio Vazquez-Abrams wrote:
Are we then going to require people to use elinks or w3m to view them,
No. I guess I wasn't clear. I was suggesting that one possibility is to use elinks or w3m *automatically* as backends for the info program or info mode:
I hope that nobody will take that seriously. Search and navigation in html variants of documentation are between poor and non-existent. A search within just displayed fragment is not coming even close.
Here I'm talking about changing file formats by the info program from info format to xhtml, as generated by makeinfo. That xhtml has all the information that the info-formatted version has (or if not it would be easy to tweak makeinfo).
By by definition, any searching that the standalone info program can currently do on info-formatted files a version of the info program modified to be able to read xhtml files would also be able to do.
Now it might be a lot of work to re-implement info functionality when using a different file-format, and it might be hard to find someone to do that work. It would probably be a lot easier to modify the info program to run makeinfo when needed.
Per Bothner wrote:
(1) Gnome/KDE help viewers and similar programs should not display pre-formatted info files, but instead either (a) format texinfo files on the fly, or
KDE's info: kioslave does exactly that already. That said, not everything is reflowed, some stuff is put into preformatted blocks. Try firing up e.g. info:pinfo in Konqueror to see how it looks like.
There's also a man: ioslave.
Kevin Kofler
On 03/06/2009 08:09 AM, Kevin Kofler wrote:
Per Bothner wrote:
(1) Gnome/KDE help viewers and similar programs should not display pre-formatted info files, but instead either (a) format texinfo files on the fly, or
KDE's info: kioslave does exactly that already.
I believe you're mistaken. It uses info2html - i.e. it starts with info files.
I'm suggesting "texinfo2html" - which might be just makeinfo --html
That said, not everything is reflowed, some stuff is put into preformatted blocks. Try firing up e.g. info:pinfo in Konqueror to see how it looks like.
I don't have pinfo installed and yum is hosed (on my laptop). But I tried info:tar. It does *not* reflow. Nor does it use any font except a mono-space font. And links cannot go a specific location in a page, just a page as a whole.
Per Bothner wrote:
On 03/06/2009 08:09 AM, Kevin Kofler wrote:
Per Bothner wrote:
(1) Gnome/KDE help viewers and similar programs should not display pre-formatted info files, but instead either (a) format texinfo files on the fly, or
KDE's info: kioslave does exactly that already.
I believe you're mistaken. It uses info2html - i.e. it starts with info files.
Actually I just misunderstood what you meant by "format on the fly".
But I tried info:tar. It does *not* reflow. Nor does it use any font except a mono-space font.
Yeah, those are the "preformatted blocks" I was talking about. Unfortunately most stuff just ends up in those. :-(
Kevin Kofler
On Friday 06 March 2009 08:26:07 Ignacio Vazquez-Abrams wrote:
Are we then going to require people to use elinks or w3m to view them, plus expect them to know where the HTML pages are stored in the first place?
No, the far more sane option is to fix info or pinfo so that it catches SIGWINCH and reflows as necessary.
They can't, because the info format is PREformatted for that size. It doesn't contain enough markup to reflow it without breaking precious content that's been carefully laid out by the author.
The advantage of things like docbook is precisely that they can be reflowed without breaking things (well, not so easily anyway).
Now, we could provide automatic translation to "man" format; or we just make "man" able to shell out to a viewer that can handle docbook, or run a translator to produce HTML on the fly, or ...
Sun converted to SGML format for man pages (I believe it was a tweaked version of DocBook) many years ago, it's possible, and it would be very nice indeed to do this.
Ignacio Vazquez-Abrams wrote:
On Thu, 2009-03-05 at 23:36 -0430, Patrick O'Callaghan wrote:
On Thu, 2009-03-05 at 15:37 -0800, Per Bothner wrote:
Fedora (and GNU systems in general) should stop shipping info files, and should instead ship the texinfo source files. The makeinfo program will convert texinfo files into html or docbook, as well as old-fashioned info. Html or docbook is much nicer - you can use non-monospace fonts (for the body), and the text can be re-flowed to fit the window. Also, indexes and cross-references can take you to a precise location, rather than just a node.
Interesting idea. Is there any reason why this wouldn't work?
Are we then going to require people to use elinks or w3m to view them, plus expect them to know where the HTML pages are stored in the first place?
No, the far more sane option is to fix info or pinfo so that it catches SIGWINCH and reflows as necessary.
I personally think having more than one format (or rather, not having everything in one format) is a pain. I don't like having to guess what format documentation us in (man, info, html, pdf, postscript or something else).
I do a significant amount of my work at consoles: right now, I have 11 terminals open, some being konsoles almost all with multiple tabs plus four virtual consoles, one of which runs screen, currently imbedding six sessions. Often my terminal sessions connect to other computers, frequently running screen remotely.
That leaves HTML, INFO and man as the only possible formats for me. Often (almost always) HTML imbeds graphic images, so I'll rule that one out too.
In maybe ten years, I've yet to come to terms with FSF's info command, I mostly just pipe it's output into less. Alternatively, I use pinfo.
Much to my surprise, info can display man pages. It's not documented as doing so (CentOS5), but I knew pinfo does, so I tested info.
A disadvantage of converting info documents to man is that info documents can contain hyperlinks, and these are lost on conversion.
On Thursday 05 March 2009 23:37:35 Per Bothner wrote:
I remember (but now can't find it) somebody commenting on the man file vs info documentation issue: that they disliked info because it doesn't reformat properly depending on window size.
Me :o)
Fedora (and GNU systems in general) should stop shipping info files, and should instead ship the texinfo source files. The makeinfo program will convert texinfo files into html or docbook, as well as old-fashioned info. Html or docbook is much nicer - you can use non-monospace fonts (for the body), and the text can be re-flowed to fit the window. Also, indexes and cross-references can take you to a precise location, rather than just a node.
I do find "info" a bit annoying, although pinfo makes it easier ...
What might be useful (kick me if it's there already and I missed it) is a page in the wiki specifically tailored to providing advice on converting to a newer format such as DocBook (which is faaaairly easily converted to other formats), such as references to doclifter, to a simple guide on how to use DocBook for a manual page, etc etc.
On 03/06/2009 04:58 AM, Bill Crawford wrote:
What might be useful (kick me if it's there already and I missed it) is a page in the wiki specifically tailored to providing advice on converting to a newer format such as DocBook (which is faaaairly easily converted to other formats), such as references to doclifter, to a simple guide on how to use DocBook for a manual page, etc etc.
To convert texinfo to docbook just do: makeinfo --docbook foo.texi
Now as a *source* format texinfo has some advantages over docbook - it is a lot less verbose, and easier to both read and write. However, docbook is more "standard" and has some extra functionality.
I don't think you're going to get the FSF to switch from texinfo to docbook as the primary documentation format. We might get them to deprecate the info *format* if the info-using tools they care about can do as good a job with docbook or html as they currently do with info files.