Posted
by
Unknown Lameron Sunday February 17, 2013 @07:14PM
from the aged-to-perfection dept.

Four years after the last release, version 5.0 of Texinfo, the GNU documentation language, has been released. The primary highlight is a new implementation of makeinfo info in Perl rather than C. Although slower, the new version offers several advantages: cleaner code using a structured representation of the input document, Unicode support, and saner support for multiple output backends. There are over a dozen other improvements including better formatting of URLs, improved cross-manual references, and a program to convert Perl POD documentation to Texinfo.

Although slower, the new version offers several advantages: cleaner code using a structured representation of the input document, Unicode support, and saner support for multiple output backends. (emphasis mine).

how often do you run makeinfo? Probably never directly. And only indirectly if you're compiling and installing a GNU package from source (I mean, who else even uses it? )-- in which case configure checks and compilation times are the bottleneck, not makeinfo

It'd only be even potentially noticeable if the end user compiles their documentation from source. That's only likely to happen if they're also compiling their binaries from source, i.e. on source-based distros. (I doubt it'd be particularly noticeable even in such cases.) Most people would get the compiled version of the documentation, rather than compiling it themselves.

What I find interesting about this Perl rewrite is that Guile, ostensibly the official scripting language of GNU, has had excellent structured texinfo support [gnu.org] for years now. It uses stexi which has the same structure as sxml, so you gain access to all of the really great Scheme XML processing tools, including SXSLT which is basically ideal for spitting out arbitrary formats.

Whenever I install Debian or a derivative of it, I always find it includes Guile, but that no packages depend on it. The only reason it exists is because RMS didn't like Tcl, which was the up and coming glue language at the time. Despite its shortcomings, Tcl was a very nice language to extend, whereas Guile was (and probably still is) an incomplete dialect of Scheme that only satisfies the Lisp obsessives.

To be honest, I have written a few programs in tcl, and it was a very clumsy syntax that I had to fight with constantly. I have better experiences with LUA, but wish they'd stopped adding "meta" smarts to it earlier than they did, they went a bit over-the-top.

Of course, in the real world I just hack everything in Perl still no matter what other scripting languages come and go...

This is interesting for two reasons:
0. It was Perl's built in features, such as regex, system calls, and ability to be terse enough to enter a solution on a single swinging pass that make it an obvious choice -- It was made for this type of job.
1. I'm confident that if we have not already, we will soon reach a point where entire discussions can be composed of no text other than xkcd links. [xkcd.com]

0. It was Perl's built in features, such as regex, system calls, and ability to be terse enough to enter a solution on a single swinging pass that make it an obvious choice -- It was made for this type of job.

Whenever the problem allows for a single pass.

1. I'm confident that if we have not already, we will soon reach a point where entire discussions can be composed of no text other than xkcd links. [xkcd.com]

Due to limited contexts available on xkcd, I surmise we are quite far at that point. E.g. I challenge you to find the very basic "laser on sharks" or "car analogies" cartoons on xkcd.com."grits" (hot or not), "petrified/statue" etc??? Not a chance in hell.

I suppose people are free to keep reading the same old, self-reinforcing sources that insist that Perl is somehow a language of the past. And if they read enough of these cliches, the anti-Perl FUD may seem to be accurate, but as any developer who spends time wrestling with real-world problems in modern Perl will attest, the so-called modern Perl ecosystem is, (just like the modern Python or PHP ecosystems), a fabulous place to work in.

Yes Perl has lots of libraries, lots of code, lots of support, and I'm sure if you spend all of your time in Perl, you eventually get used to it. But I spent time working on occasion on some Perl scripts we used for glue, and from that point of view, Perl is a nightmare. Random crap done by random characters depending on random context. Basically it looks like whenever Larry Wall needed to do something, he added some functionality and assigned the next unused character combination to it. I've programmed

I must admit, one of my issues with Perl isn't really Perl, it's the Camel book. It seems to be deliberately written out of order so whatever you are reading, it's guaranteed that you need to read something later in the book first.

Maybe you should run Debian or a derivative? Debian are big on man pages and will write them if they don't exist.

True, though only sort of. In my—admittedly dated (last I used regularly was etch)—experience of Debian, if I'd had a dollar for every package of which the "man page" was simply a placeholder because policy required the packager to have something, I could have bought us both dinner, to say the least.

I haven't used TexInfo for years, but what I remember most was the absolutely abysmal standalone "info" reader. That thing was the biggest piece of shit I've ever seen in any program. Hopefully they've abandoned the crappy "info" format and all of the shitty standalone readers to view info documents, and just use HTML by default now.

The 1990s, when HTML documents were readable and not stuffed to the gills with ads and social recommendation detritus. Really all a plain-jane HTML document is missing is a max-width:36em on body to make line lengths sane and a width=device-width on the viewport to make tablets not render it zoomed out.

Yes. It's usually broken up into a massive hierarchy with a couple of sentences per page. You'll get cramps clicking on the navigation links while searching for the particular thing you need to find like a needle in a haystack.

Plain old man pages (especially when nicely rendered in KDE's Konqueror web browser by typing "#program-name" into the URL box) are almost invariably superior to the corresponding Texinfo docs converted to html.

C and shell scripting is good enough for me and it should be for any GNU project. I do not use half-way solutions such as Perl. I use Java when bash and C becomes too messy. The idea is to reduce your inventory to a strict minimum.

GCC is C. This is a job for a scripting language not a low level compiled language. Typically GNU uses Scheme as their scripting language. But knowledge of Scheme and Scheme syntax is decreasing. Perl has good support for parsing, tons of people know it, It seems like a reasonable choice for GNU to start doing scripting type stuff in. The Perl community has been active with free software for a long time and hasn't gotten involved in anything questionable.

How is perl any more "outside of the GNU system" than TeX? Which is, after all, what texinfo is based on.

The GNU project's goal is to implement a free OS. Not to re-invent every wheel. (Except for the kernel, but that's just follow-through--work on the GNU kernel started before other free kernels were available.) Perl has a GNU-compatible license--why shouldn't they use it?

Eventually, they'll make guile able to interpet perl code, and the problem will solve itself.:)

The fact that Perl isn't even a GNU project means that they don't even have an excuse of wanting to stick with GNU for picking a crappy language to work with! If they were going to go outside GNU, there were dozens of free languages that they could have picked that would have been a better choice.

Honestly, about the only worse programming language choice I think they could have made is if they decided to redo TeXinfo in COBOL.

I suspect the person who wrote the code disagrees--or else he would have used a different language. Working code trumps theoretical BS and religious language wars any day in the real world. If you hate perl so much, write your own version in your own preferred language, and offer it to GNU and see what they say. If you're not willing to put your code where your mouth is, though, then your opinion isn't worth squat.

And for the record, I disagree as well. Perl has plenty of warts, but it's got plenty of stren

Possibly... but here they just made a crappy choice period. And the fact that it's not even really part of GNU means that they don't even have an excuse for it other than ignorance.

Perl is not a remotely elegant or clean language to develop in, and I have completely lost count of the number of projects I've seen written in it, as they evolved, showed a distinct propensity to quickly *DE*volve into an undecipherable mess. It's a language that is best avoided in the 21st century, because there are many a

I love how a language that was "fast enough" in the '90s is now suddenly "too slow" in 2013.

No-one said it was "too slow", if they thought that they wouldn't have released it. They said it was slower than the C version, which is (presumably, as I haven't measured it myself) an objective fact.

Every time I run man and get a pointer to texinfo, I want to beat my head on the keyboard. I do not have the time, once again, to look up those obscure keyboard commands so that I may navigate laboriously through the documentation. It's time to interrupt my command-line workflow, go to the nearest GUI and run a web search for the nearest HTML manual.

It was even worse when you type "man foo", get a message telling you man is evil and to use info, then the info gives you nothing but a placeholder. The gnome stuff was full of that (gconf stuff especially) before they decided to not even bother pretending they had documentation.Back in the day doing "man grub", getting a rude message to use info, then "info grub" and getting a "grub is wonderful LILO sux" message and no documentation was definitely one of those moments where I wanted to beat somebody's head with a model M keyboard.At least "pinfo" can be used without having to spend more time working out how to use the info tool than reading the documentation.

info shows the manpage by default if the info documentation isn't installed. So what you're seeing is probably a packaging problem, where the documentation exists but, for whatever reason (perhaps you're using a Debian-based distro and forgot to explicitly ask for it), wasn't installed on your computer.

Both texinfo and man have their place. texinfo is good for learning the deep details of a product. man pages are good for quick "what was that option for doing X again?" checks.

The attitude of the FSF towards man pages is, to put it politely, stupid. And counterproductive. Damnit, the response to a bug report saying "the man page is out of date/inaccurate/incorrect" should be to fix the damn man page, not to remove it!

Don't get me wrong, there are times when the texinfo documentation is incredibly useful, a

Texinfo is is a decent format for writing documentation in - nicer and less verbose than HTML or DocBook.
You can generate either HTML or DocBook or XML from Texinfo, and then do a bunch of processing on it.
For example the documentation for Kawa [gnu.org] is written in texinfo, then makeinfo converts it to docbook, which is then converted to html.
The result isn't splashy but (if I say so myself) fairly nice.

Aside from the fact that it's Just Plain Horrid(TM) to read or write in source format, TexInfo suffers from the same problem that HTML does: No semantics.

You don't seem to know much about Texinfo. It is definitely very much about semantics - quite like DocBook.
I agree DocBook takes the semantics thing slightly further than Texinfo - but it has big holes too: For example
DocBook doesn't have a standard way to specify the structure of a command/function synopsis except for the C language.

It's clear that DocBook was written by a couple of groups who each had their own documentation needs in mind. So firstly there are more-than-one-way-to-do-similar-things clashes, and if you're not trying to write something that's just like one, and only one, of theirs - you'll end up with a bit of a 3-legged camel.

Regex search over the entire info document is something I use a lot, and HTML doesn't (natively) support. (Index search via typing the name of an index entry, and then jumping to other entries that match the same string, is another thing that HTML doesn't do well.) These are arguably deficiencies in HTML, and could be fixed with mindboggling amounts of JavaScript or by doing things server-side, but both seem to be missing the point to some extent.

Pinfo is an info file viewer. It was created when the author, Przemek Borys, was very depressed trying to read gtk info entries using the standard tools.

Pinfo is similar in use to lynx. It has similar key movements, and gives similar intuition. You just move across info nodes, and select links, follow them... Well, you know how it is when you view html with lynx.:) It supports as many colors as it could.

Every time I run man and get a pointer to texinfo, I want to beat my head on the keyboard. I do not have the time, once again, to look up those obscure keyboard commands so that I may navigate laboriously through the documentation. It's time to interrupt my command-line workflow, go to the nearest GUI and run a web search for the nearest HTML manual.

Thank you, sir. That's something I would have said myself precisely like that.

I do not have the time, once again, to look up those obscure keyboard commands so that I may navigate laboriously through the documentation.

What obscure keyboard commands? They're just the keybindings for the help system of the One True Editor. If you are using something inferior and have therefore memorized some truly obscure keyboard commands instead, how is that their fault?

It's weird, I've seen a reference to texinfo many times while using man, but I have never actually followed through. Texinfo was just the weird disclaimer on some man pages to me. I just did info grub now, and it's not that bad if you stick to page up / page down and searching, like with man. Maybe I'll start actually using the texinfo pages now...

Every time I run man and get a pointer to texinfo, I want to beat my head on the keyboard. I do not have the time, once again, to look up those obscure keyboard commands so that I may navigate laboriously through the documentation.

Then just pipe it through your pager, and you'll have basically the exact same experience as if it was a man page. e.g.:

No oxymoron here. Perl frees you to create real messes, but that's mostly because it's very expressive, which also helps you code with less temp variables, shorter loops, etc., which can be actually easier to read if you know the language (Perl has a higher "cognitive load" than other languages that may alienate casual participants).

OTOH there are best-practices and style guides to ease things for the next lucky person to read your masterpiece (possibly a future you). So don't blame the language; hell, ther

That TIMTOWTDI meme is somewhat exaggerated, and not the same as expressiveness (which is what I was talking aboui). Likely, among the 3-4 ways that you may find to do something, some are obsolete or too complicated, some are misleading to anyone else reading the code, and you're left with one that's simple and "natural" for your purpose. Let me explain:

*sigh*... I can hardly defend something that's not under attack. I posted some information that may or may not be useful to someone afraid of Perl, and it's up to said person to consider it, take it at face value, or throw it away with prejudice. Everyone is free to use it even if someone else hates it or trolls against it, and I'm happy using it for what it's good for. Cheers.

Now we will have a perl dependency for all GNU stuff, and this to read documentation that is even less nice to read than man pages. The best thing they could have done to texinfo is to get rid of it, IMO.

I very happily gave up on man pages (and variants thereof) years ago because they were too obtuse and circular to be useful to me, a mere end user. Early on I figured out that the basic rule of man pages was that the one you need relied on you already having read and digested fifteen others, each of which relied on you having read an digested fifteen others.... actually finding what you needed was an endless exercise in frustration.

It has been used as a pretext for not providing correct man pages. For example man sed:
COMMAND SYNOPSIS
This is just a brief synopsis of sed commands to serve as a reminder to those who
already know sed; other documentation (such as the texinfo document) must be con-
sulted for fuller descriptions.

When I have learned unix, man pages were complete, concise, accurate and uptodate documentation of all the system. I feel that because of this textinfo mess, man pages on Linux are incomplete and vague and that the documentation dislayed by info is not very clear.

This net bsd documentation of sed is incredibly better that the one I have on Linux. It is almost perfect. In 5 minutes, I have found only one point of ambiguity: it says it is a superset of posix.2, but I do not find the possibility to use a dash instead of a file to mean stdin. Maybe there are others issues, but this is clearly a better documentation (should I switch to netbsd ?).

I'd rather see the format scrapped and replaced with either better man pages or else HTML2. With HTML 2 you can use a text based browser like Lynx, which is more polished and gives you better navigation capabilities. There are also more modules, libraries and packages that can work directly with HTML, so less time is spent trying to reinvent the wheel.

It's very handy for generating both nroff man pages and their HTML counterparts from the same input text. Being extremely simple, it raises no barrier to writing man-page type documentation.

Neither does nroff -man.
If you're in a position where you'd want a man page, a percieved complexity in writing one in nroff is no excuse.
Read man(7), groff_man(7) and groff_char(7), and look at some example man pages for inspiration.

Also, if the cvs(1) man page of CVS 1.12.13 is a typical example of what Texinfo generates, I strongly recommend against using it for this. It's ugly and hard to read; doesn't really look like a man page at all.

Sorry, but the world works the way it works, and does not magickally conform itself to your views on How Things Should Be.

I don't like perl, either. ("Loathe" might not be too strong a term.) But neither am I foolish enough to believe that I am likely to wind up with a usable Linux or FreeBSD system if I try to set one of those up without it.

I think that calling C "portable assembly" is really a bit untrue. One of the core features of most any machine language is that flags are part of the result of many computing operations. Yet C completely removes access to it.

Suppose you have a code that adds two things, then jumps on overflow. On most machines that's two instructions if the operands have the right size. You look at it, and the intent is obvious: we add, then jump on overflow.

Things are seriously wrong (IMHO) if a higher level language completely obfuscates this and requires code where it's not obvious at all what you mean! Heck, what's worse, each compiler likely requires slightly different code so that the meaning is extracted by the optimizer and the correct assembly output is produced without paying both code size and performance penalties! In C, the best you can do on a good compiler is to have an inlineable function that returns the numerical part of the result, uses comparisons to "recreate" the detection of overflow, and returns the overflow condition in a char* out-parameter. If the optimizer is good, it'll recognize that the out parameter accesses an automatic variable in the caller, and that your comparison is just checking for overflow. This code, while portable C, will perform horribly as soon as you compile it without state-of-the-art optimization capabilities. I'd think that means that if your compiler wasn't released in the last year or two, and isn't a mainstream decently optimizing one (like gcc, llvm, visual studio), you're out of luck. On many platforms a saturating increment/decrement is also two or three assembly instructions at most, without jumps -- but good luck getting a compiler to actually emit such code.

I think that providing no way to access the flags part of arithmetic operation results is one of the biggest oversights in C. I'd think that every platform C runs on provides such flags.