Randall R Schulz wrote:

On Tuesday 29 July 2008 08:23, Alexey Eremenko wrote:

...

PDFs are really slow to open. If you learn some new topic and open 20-30 man pages then it is very fast. Try that with PDFs.

I dislike PDFs for performance. I prefer man pages, info, or HTML.

I'm with Duaine.

HTML is a hideous medium for publishing. Info makes me gag. Paging through the CLI man viewer is tedious. Printing from any of these media is very problematic. And just how do you concurrently view your "20-30 man pages?"

Performance problems are almost always transient. If someone wanted a fast-launching PDF reader, they could produce it. Hell, you could integrate it into the kernel. (It works for Microsoft...)

I have no problem with man pages in PDF format - as long as they also remain readable without a GUI.

/Per Jessen, Zürich

Rajko M. a écrit :

...

I have no problem with man pages in PDF format - as long as they also remain readable without a GUI.

I think man pages, as HOWTO, are built to be easily converted in many formats, using pdf wont be of any problem.

any format given by script tools is ok.

What I can say is that the LDP (Linux Documentation Project) is aiming to work around a wiki, probably moinmoin as this one can do docbook in/out and docbook is the natural source format of the ldp.

Ldp hosts also man pages (at least I receive any an pages updating on tldp lists) and - may be - could accomodate them into his wiki. from then, any print utility can do pdf.

I will discuss this more in depth in a while, because we (at ldp) need help from distros, but we are now waiting for a new hardware (the present one is unable to cope with the work), so we have to wait for this new hardware to say more

jdd

----- Original Message ----- From: "Randall R Schulz" rschulz@sonic.net To: opensuse@opensuse.org Sent: Tuesday, July 29, 2008 11:29 AM Subject: Re: [opensuse] man pages and PDF

On Tuesday 29 July 2008 08:23, Alexey Eremenko wrote:

...

PDFs are really slow to open. If you learn some new topic and open 20-30 man pages then it is very fast. Try that with PDFs.

I dislike PDFs for performance. I prefer man pages, info, or HTML.

I'm with Duaine.

HTML is a hideous medium for publishing.

Html is a great, basically _ideal_, format for publishing. Especially for content like man pages. There may be a few even better formats, but they are merely the same idea as troff & html taken a little further. Like tex/latex. ie: markup & style based.

Html is merely no longer good for what most people want to get out of web sites and web pages. They really shouldn't probably even be called web "pages" any more, since the last vestiges of the web being like docuents is pretty much gone. Web sites & web pages are more like applications now. But that's web sites, not man pages. documentation is still, uh, documentation, ie, documents. Html is just wonderful for documents.

Info makes me gag.

All in all I hate info too, but for pretty specific reasons, not just because "info makes me gag"

Info, like, troff, html, tex, etc.. is a perfectly fine format for ducuments. It's features exactly match the job.

The only thing I see as bad about the format itself is the index/toc files. Really dumb. Man-pages are self contained. To install and view a man page you simply copy it or view it. To install an app with it's man page, you can simply untar it, no install script needed. But info requires you to correctly edit an index file to integrate your new documents in with all the others...*headsmack*

And I have never met an info viewer app I could stand, and there are damned few and poor of those incomparison to other formats. That is purely a viewer app problem, and an "I happen to hate emacs keybindings" problem, not a document format problem.

pdf by comparison, is intrinsically terrible for the job man-pages need to do, which job includes being available at all times via even the most limited interfaces. If all else fails, you can actually just read a man page directly in a plain text pager, or just cat it to your tty even, and mentally ignore the markup commands. You can't do that with a pdf.

Paging through the CLI man viewer is tedious.

If you don't know enough to use the search function in your viewer of choice, to jump to what you want, that's hardly the document format's fault. Besides how is that any different than paging through a pdf? If what you're _really_ taking about is the difference between a text vs a gui viewer, well there are many gui man viewers that work more or less the same as any pdf viewer. You're inability to find and use a document viewer, as long as they exist, also is not the fault of the document format.

Printing from any of these media is very problematic.

Huh? The format was a printable format before is was a screen viewable one! Really it attempts to be output device agnostic, just like html (talking design, not retarded web developers implimentations), but the first output devices were printers and then tty's that more or less emulated printers. It's maybe not as easy as falling asleep but not exactly problematic. Pretend I don't know anything, I google "print man page" I get mostly linux-specific answers but, that's ok it's only slightly different for other *ix.

man -t foo |lpr

what, you want gui? yelp man:foo

Hoy cow that was hard.

And just how do you concurrently view your "20-30 man pages?"

Huh? uh, multiple telnet/ssh/xterm windows? gnu screen? virtual consoles at the console? Not exactly baffling rocket science.

Performance problems are almost always transient. If someone wanted a fast-launching PDF reader, they could produce it. Hell, you could integrate it into the kernel. (It works for Microsoft...)

No it doesn't. Pdf's are ridiculously slower and more cpu intensive to open on Windows than say, html. Every part of handling pdf's (storing, generating, editing, printing, viewing,...) is ridiculously more work than simple text + markup like troff & html to view the same exact content.

Having a fast, mostly un-used cpu in your particular desktop that hides the overhead doesn't make the system efficient. When a given server that normally could generate print-to-html output and display it in the users web browser or email client instantaneously and support say 200 users doing that, the same server can only support say 75 if all those print jobs suddenly became print to pdf jobs. It's absolutely gross. Ask me how I now. Now multiply that by 30 servers... And even with as much of the workload as possible on the server and the servers load reduced by reducing the number of users to compensate, it's still not as convenient for the end user simply because the pdf takes way longer to open in an email client, and appears as an attachement that must be clicked to view it first. No email client yet lets you flip quickly through all your emails and read & discard them right from the preview pane, including the pdf attachements. But plain text & html work fine. They are right there, already rendered and readable without needing to be opened. I can tap through 60 emails in 30 seconds. If they were all pdfs, no matter how fast my machine was it't be at least several minutes. I don't even want to think about downloading 60 pdf attachment emails and then viewing them on my palm phone, yet text & html re no problem at all for speed, size, & client viewer. And on the server side the work to create the text or html email or the temp web page was approximately "cat" merely reading and copying a few k of text. Thats no remote comparisn to what ghostpdl or ghostscript or any other util has to do to generate a pdf of the same text.

Man pages are intended to be accessible from any interface, least-common-denominator. Even if you are dialed in via 9600 baud modem, no tcp/ip, no multiple windows (except maybe via screen or other tty multiplexer), no gui, non-standard display size (8x40 character lcd display?), any kind of terminal including uber dumb terminal with no ansi features and only 7 bit ascii, you can still view any man page. Anything that removes that universal access is a step backwards not forward, since there is no need or excuse for it. The man page format, while old and a bit simple, does allow for fairly nice rendering options on output devices that can support them.

I would have to hear a description of a job a man-page should do, that troff, or some other equally efficient and simple markup system, doesn't provide a means to do, before I'd consider this argument valid enough to even talk about at all. All the supposed points above fail that test.

Examples might be: Display graphics/diagrams. Even for basic CLI utils, there is occaional need for such. Wiring diagrams & signal timing diagrams for serial or other i/o ports, mathematical equations, flow charts and block diagrams describing how a subsystem works or interacts with other subsystems, etc... Hyperlink to other man pages or specific items within other man pages.

Hyperlinking is easily handled by switching to merely a different markup system that happens to have that. That seems to have ben the main idea behind info. (which is basically just tex) Graphics is not so simple. html obviously provides a way to display them while still being a simple plain text markup system, but, should graphics be embedded in the man pages like mime emails with cid:// links? should man-pages maybe be mime formatted for that matter (mime is not an email standard but a generic one) or should the text of a man page remain as small as possible with img links pointing to seperate files, thus allowing man pages to be riddled with broken links...

I'd be interested to hear of any other ideas for things man pages should do but currently can't.

Brian K. White brian@aljex.com http://www.myspace.com/KEYofR +++++[>+++[>+++++>+++++++<<-]<-]>>+.>.+++++.+++++++.-.[>+<---]>++. filePro BBx Linux SCO FreeBSD #callahans Satriani Filk!

On Wednesday 30 July 2008 06:49:57 Randall R Schulz wrote:

On Tuesday 29 July 2008 22:14, Brian K. White wrote:

...

----- Original Message ----- From: "Randall R Schulz" rschulz@sonic.net To: opensuse@opensuse.org Sent: Tuesday, July 29, 2008 11:29 AM Subject: Re: [opensuse] man pages and PDF

...

...

I'm with Duaine.

HTML is a hideous medium for publishing.

[nod]

Whatever you say.

But please don't impugn my knowledge of Unix / Linux commands and operation.

And, maybe, get a blog for you bloviations.

Indeed.

That said, the command posted for converting man pages to Postscript output is quite suitable for print matter. Using PDF or Postscript for online documentation is a sorry idea unless you happen to have a system that has built-in display Postscript (I'm thinking NEXT, here). For the rest of us mere mortals, man is fine. It will work on the most primitive 80x25 teletype display. Good luck with viewing PDFs or Postscript out on that same 80x25 TTY.

Kurt

On Friday 01 August 2008 02:59, Carlos E. R. wrote:

The Thursday 2008-07-31 at 21:04 -0700, Kurt Wall wrote:

...

that has built-in display Postscript (I'm thinking NEXT, here). For the rest of us mere mortals, man is fine. It will work on the most primitive 80x25 teletype display. Good luck with viewing PDFs or Postscript out on that same 80x25 TTY.

mc displays pdf as plain text. Imperfectly, but it does

However, I would not like man pages to be pdfs: for instance, "apropos" would fail or be terribly slow.

Clearly PDF would not be the sole or even a primary format, but just one of the available ones.

Clearly man pages still need to be authored and maintained, and unless someone's going to create, say, a TeX reimplementation of the man macros for troff and reformulate all those man macro-based source files, the current originals will continue to be the primary source format for man documentation indefinitely.

-- Cheers, Carlos E. R.

Randall Schulz

Alexey Eremenko wrote:

PDFs are really slow to open. If you learn some new topic and open 20-30 man pages then it is very fast. Try that with PDFs.

I dislike PDFs for performance. I prefer man pages, info, or HTML.

I really like html. For a beautiful example of _good_ documentation, have a look at http://www.tcl.tk/doc/.

I don't like pdf docs because there's usually very little hyperlinking. Whether that's a defect of the pdf environment or of the writers, I don't know.

John Perry