source format vs info/html

Posted Dec 15, 2014 14:08 UTC (Mon) by fb (guest, #53265)
In reply to: source format vs info/html by nix
Parent article: Emacs and changing documentation formats

All you (for the lack of better words) 'love to use info' folks need to do a reality check. Whether or not you can figure out *where* info failed, you ought to reckon that info *failed badly* at its presentation and user interface.

Here you are at LWN of all places, and a bunch of seasoned Linux/Unix users telling you: "I could never figure it out" etc. You really ought to reckon that, at the very least, something went very wrong in communicating how to use info or at its usage assumptions.

Wrong assumption: I use/do a lot of stuff from within emacs, but I don't live inside emacs (I'm sure you all understand what this means). If the assumption from the GNU project was that folks ought to live inside Emacs to read GNU programs' manuals then they really got things wrong.

Bad documentation: if using info is so easy ("all you need are keys space/backspace/u/q"), and if that is really everything I need to know about it, why the heck isn't that written in info's manual? I mean, where else do you expect that non-info users will look for how to get started using info? I tell you: 'man info'. Please open 'man info' and try to read it as someone who has no clue about 'info'. Guess what? You'll be done reading that and you will still have no clue about how to use it.

source format vs info/html

Posted Dec 15, 2014 15:33 UTC (Mon) by rleigh (guest, #14622) [Link] (3 responses)

I think in this discussion there is some lack of distinction between the various pieces:

- the texinfo .texi source format
- the info .info viewer format
- the viewer program (info/pinfo/emacs/yelp/...)

The .texi source format can be replaced with e.g. Sphinx or DocBook, both of which can be translated to .info as well as more modern formats such as HTML and PDF. Having written a manual in .texi, I think it's fair to say it's OK if you like a LaTeX-style markup, but maintaining the section links is painful and easy to screw up, and while the format is good, it does have limitations. Using Sphinx (or even DocBook) is generally easier to write and maintain. And despite being TeX-based, the .texi table support is fairly woeful; not that Sphinx or DocBook are amazing, but they are both much better, as is basic troff tbl. Support for figures and images is also fairly rudimentary. Generally I think that the .texi source format is due for retirement; the replacements are generally nicer and simpler to use.

On the viewer side, I agree it seems less simple than man/less. While the added structure does seem nice, in practice I always seem to end up searching for what I need or using the index. That said, I do think the criticisms are somewhat overblown; even the basic info viewer is perfectly functional. There is significant room for improvement though, particularly on the Emacs side where it can draw on the rendering features of the editor.

The .texi manual I wrote was converted to DocBook a decade back. And all the stuff I currently maintain is either manpages (with translations via po4a) or Sphinx. Both are far nicer to maintain than .texi. I think the days of .texi as a source format are waning, but this is relatively independent of the .info viewers.

Regards,
Roger

source format vs info/html

Posted Dec 15, 2014 17:31 UTC (Mon) by nix (subscriber, #2304) [Link] (1 responses)

Sphinx I agree with -- it really *is* nice to write. But, DocBook? It's a hell of HTMLish (OK, XMLish) redundancy that essentially mandates specialized tools to write it. Yes, you don't have to duplicate node info: instead you have to duplicate *almost every single piece of markup*. I cannot call this an improvement.

source format vs info/html

Posted Dec 15, 2014 19:03 UTC (Mon) by rleigh (guest, #14622) [Link]

I should clarify that I consider DocBook to be pretty awful to author. It's a decade since I last used it in anger; the last time was just to update the PostgreSQL manual as part of a patch. I mentioned it only because it's possible to convert to info, not because I'm in any way recommending its use! I find more minimal tools like Sphinx vastly more suited to writing and maintaining documentation these days!

source format vs info/html

Posted Dec 15, 2014 18:22 UTC (Mon) by Per_Bothner (subscriber, #7375) [Link]

"maintaining the section links is painful and easy to screw up"

Note that with recent version of texinfo format, the cross-references (forward/back/up) in the @node command are optional. It's best to just leave them out.

source format vs info/html

Posted Dec 15, 2014 16:18 UTC (Mon) by mbunkus (subscriber, #87248) [Link] (5 responses)

I do agree that info has failed somehow, but:

1. »man info« pretty much tells you to type »h« inside info itself in order to get help on key bindings. Citing »man info«:

> For a summary of key bindings, type h within Info.

2. When you run info (the program) then the bottom line will read »Welcome to Info version 5.2. Type h for help, m for menu item.«.

Hitting that aforementioned »h« inside h will get you exactly the information you need.

So I do dispute the claim that how to use info is not documented enough.

source format vs info/html

Posted Dec 18, 2014 20:37 UTC (Thu) by Wol (subscriber, #4433) [Link]

Unfortunately, it is. As someone who has - on several occasions - done pretty much as you suggest, I still hate the damn thing with a vengeance because I just cannot get to grips with it!!!

Cheers,
Wol

source format vs info/html

Posted Dec 18, 2014 22:29 UTC (Thu) by bronson (subscriber, #4806) [Link]

Quite the opposite -- it's OVER documented. Using info requires reading so much documentation that I just can't be bothered. Why doesn't it behave like other Unix utilities? (Emacs doesn't count)

source format vs info/html

Posted Dec 19, 2014 10:53 UTC (Fri) by fb (guest, #53265) [Link] (2 responses)

@mbunkus sorry, but the version of the info manual present in my computer does not contain that string.

It seems OSX ships a version of info which is from Dec 2004 (Info version 4.8). (at work I pretty much sit the whole day inside OSX).

So while the documentation may have been fixed recently to address many usability issues. This old man page shows (as far as I am concerned) why so many people that made an honest attempt to use info 'back in day' did not succeed and pretty much learned ways to avoid using it.

source format vs info/html

Posted Dec 19, 2014 14:10 UTC (Fri) by oldtomas (guest, #72579) [Link] (1 responses)

> It seems OSX ships a version of info which is from Dec 2004

This could be an instance of "Steve's wrath": AFAIK Apple hates GPLV3 and prefers treating its customers to outdated Gnu software before even coming close to this license (Bash's another typical case: watch Apple's strange dance in the shellshock drama).

Whether that's in your (as Apple's customer) interest is quite another thing...

source format vs info/html

Posted Dec 19, 2014 14:36 UTC (Fri) by fb (guest, #53265) [Link]

I'm well aware that Apple is not updating anything re-released as GPLv3. No, I don't think this is in my interest as an Apple _user_ (the Apple customer in question is my employer).

[...]

I am seriously /not/ an Apple fan. But from my experience working for large IT companies, I don't think it has much to do with a former CEO's wrath or not. My **guess** is that something like this took place:

1. when the GPLv3 came out, folks in charge of updating utilities knew they had to get Legal to approve the new license. They asked Legal. Legal said "nope".

2. the (GPLv3 inclusion) request won't ever get reevaluated without pressure coming from product managers, and I suppose Apple product managers really do not have that anywhere in their priority list.

[...]

Bash's shell-shock back and forth of fix-attempts was, in my understanding, embarrassing for everyone.