[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

RE: Re: Manual Pages

From: Mark Moore <mark.moore_at_notlimited.com>
Date: 2007-01-24 16:50:43 CET

I just wanted to add my voice to the benefits of man pages when working in a
command line environment.

As Nadav speculates in his post, there *are* existing tools to extract man
pages from HTML. And, the XML that almost certainly is the source behind
the online svnbook is designed to be rendered in multiple formats (e.g. HTML
& PDF).

Nadav's justification that you may need to use the electronic reference
while off-line is misdirected since only very unique (and likely
uninteresting) installations would have the client, server, and engineer
completely off-line. It's far more likely they're distributed across two or
three nodes connected by a network with access to the wider internet. And,
in the rare situation they are all off-line, they could have downloaded the
book as mentioned by others.

The answer to "Why bother with man?" is that there may not be a graphical
environment handy while you're working on your svn installation.[1] When an
administrator or an engineer is interacting with svn, there are many
reasonable situations where they might not have access to HTML or PDF
rendering.[2]

On the info vs man question, this is a false dilemma. I have a personal
preference for man, but if the reference pages from svnbook were available
in info format, that would be acceptable (imho) and a huge improvement since
the information would then be available in a command line world. The real
question is whether "svn help" and svnbook together are sufficient or not in
such an environment, and I believe it's self evident they're not.

-Mark

[1] As an aside, svn development itself eschews any dependence on a GUI
environment offloading this responsibility to other completely separate
development projects. So it seems to have some recognition of the existence
and utility of non-GUI environments.

[2] Although there are tools that can render arbitrary HTML (and PDF?) to a
command line console, the results are unacceptably poor.

-----Original Message-----
From: Nadav Har'El [mailto:nyh@math.technion.ac.il]
Sent: Wednesday, January 24, 2007 7:01 AM
To: Kenneth Wood
Cc: Brad Bruce; Adrian Howard; Subversion Mailing List (E-mail)
Subject: Re: Re: Manual Pages

On Wed, Jan 24, 2007, Kenneth Wood wrote about "RE: Re: Manual Pages":
> Consider that "man" pages existed before the internet. So, if you didn't
> have
> the info locally, you didn't have it.
>
> Now, everything you need is in the book on line. Why bother with man
> pages?

Well, obviously in some places, there is no Internet connection.
But that's not really the issue, because people without an Internet
connection
can also get a copy of the svnbook, and use a local copy.

The real issue is that man pages are simply convenient, at least of die-hard
Unix fans like myself. You're ready to type a command, and suddenly don't
remember exactly how to use it, so you type "man svn-info" (or whatever) and
get all the information about how to use this command. Not philosophy of
version-control, not server installation instructions - just (and all) the
information about the command you wanted to use.

Compare this to going to Google, typing "svn info" and hoping that it turns
up in the top result. If it doesn't, or points to the wrong version of the
book, you need to go into the svnbook homepage and start digging until you
get to the appropriate section. Some users - like myself - actually find
this much less convenient than man-pages.

Like I said, I wouldn't have even suggested this idea if someone had to
write these manual pages from scratch, because I know that this takes time
that nobody has. But the point is, the "svn subcommands" subsections in the
book are already look like man pages and don't need any text change! Someone
familiar with "docbook" (and unfortunately I'm not) could probably convert
them automatically to manpages. I wouldn't even be surprised if such a tool
already exists (but I don't know).

-- 
Nadav Har'El                        |    Wednesday, Jan 24 2007, 5 Shevat
5767
nyh@math.technion.ac.il
|-----------------------------------------
Phone +972-523-790466, ICQ 13349191 |I put a dollar in one of those change
http://nadav.harel.org.il           |machines. Nothing changed.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Wed Jan 24 16:51:27 2007

This is an archived mail posted to the Subversion Users mailing list.