You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@subversion.apache.org by Nadav Har'El <ny...@math.technion.ac.il> on 2007/01/24 11:15:17 UTC
Manual Pages
Hi, I've been wondering why the Subversion commands do not have manual
pages. Why can't I run "man svn" or "man svn-checkout" and expect to see
something useful?
It's not that "nobody found the time to write them yet", as you often hear
in other projects in reply to this questions. The thing is that someone
*already* wrote such manual pages for the "svn" command, and they can be
found in the "svnbook". See
http://svnbook.red-bean.com/nightly/en/svn.ref.html#svn.ref.svn
And proceed with "next" to see fine manual pages for all the svn subcommands.
Wouldn't it be useful to be able to see these manual pages with a simple "man"
command, instead of needing to do a search on the Internet?
Is there anywhere else where I should be raising this question, instead of
in this list?
Thanks,
Nadav.
--
Nadav Har'El | Wednesday, Jan 24 2007, 5 Shevat 5767
nyh@math.technion.ac.il |-----------------------------------------
Phone +972-523-790466, ICQ 13349191 |Make it idiot proof and someone will make
http://nadav.harel.org.il |a better idiot.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: Manual Pages
Posted by Brad Bruce <NJ...@Verizon.net>.
Adrian Howard wrote:
>
> On 24 Jan 2007, at 11:37, Nadav Har'El wrote:
> [snip]
>> The example that bothered me was the "info" command. Compare "svn
>> help info"
>> to http://svnbook.red-bean.com/en/1.1/re13.html
>>
>> "svn help info" is way too short and is missing a lot of information.
>> What
>> kinds of details can "svn info" print? Does it access the repository, or
>> just the working files? All this information (and no useless "cruft") is
>> in the aforementioned Web page, which could make a very good manpage, so
>> why not?
> [snip]
>
> I imagine that the "why not" is that the people committing to the book
> already have more than enough to do, and either manually splitting
> stuff out to man files - or figuring out a way of doing it
> automatically - is lower on the priority list than their other tasks.
>
> I'm sure patches would be welcome :-)
>
> Adrian
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
> For additional commands, e-mail: users-help@subversion.tigris.org
>
>
The book is already seperated into individual pages.
(http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.status.html)
Now to automate that to feed into the source <G>
Brad Bruce
Re: Manual Pages
Posted by Adrian Howard <ad...@quietstars.com>.
On 24 Jan 2007, at 11:37, Nadav Har'El wrote:
[snip]
> The example that bothered me was the "info" command. Compare "svn
> help info"
> to http://svnbook.red-bean.com/en/1.1/re13.html
>
> "svn help info" is way too short and is missing a lot of
> information. What
> kinds of details can "svn info" print? Does it access the
> repository, or
> just the working files? All this information (and no useless
> "cruft") is
> in the aforementioned Web page, which could make a very good
> manpage, so
> why not?
[snip]
I imagine that the "why not" is that the people committing to the
book already have more than enough to do, and either manually
splitting stuff out to man files - or figuring out a way of doing it
automatically - is lower on the priority list than their other tasks.
I'm sure patches would be welcome :-)
Adrian
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: Manual Pages
Posted by Nadav Har'El <ny...@math.technion.ac.il>.
On Wed, Jan 24, 2007, Adrian Howard wrote about "Re: Manual Pages":
> On 24 Jan 2007, at 11:15, Nadav Har'El wrote:
> >Hi, I've been wondering why the Subversion commands do not have manual
> >pages. Why can't I run "man svn" or "man svn-checkout" and expect
> >to see
> >something useful?
>
> Is there anything that man pages would give you that
>
> svk help <command>
>
> wouldn't?
The example that bothered me was the "info" command. Compare "svn help info"
to http://svnbook.red-bean.com/en/1.1/re13.html
"svn help info" is way too short and is missing a lot of information. What
kinds of details can "svn info" print? Does it access the repository, or
just the working files? All this information (and no useless "cruft") is
in the aforementioned Web page, which could make a very good manpage, so
why not?
Other pages on the svnbook site have different advantages over the
corresponding "svn help" result. Some have examples of typical usage,
information on what happens in exceptional cases, and more.
--
Nadav Har'El | Wednesday, Jan 24 2007, 5 Shevat 5767
nyh@math.technion.ac.il |-----------------------------------------
Phone +972-523-790466, ICQ 13349191 |Life's a bitch, but god forbid the bitch
http://nadav.harel.org.il |divorce me -- Nas
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: Manual Pages
Posted by Jeff Smith <js...@robotronics.com>.
On Wednesday 24 January 2007 08:45, B. Smith-Mannschott wrote:
> On 1/24/07, Jeff Smith <js...@robotronics.com> wrote:
> > First of all, you said "someone *already* wrote such manual
> > pages", but then you point to HTML pages. Do you not understand
> > the difference between "man" and "HTML"?
>
> Do you not understand the difference between HTML, and the and
> DocBookXML sources it was generated from? (I'm afraid you set
> yourself up for that retort.)
Yeah :)
It was more of a deliberate generalization, thinking, "nobody writes
HTML anymore, just other markups that look the same to end viewer, or
are translated to)
And sorry Nadav Har'El, I misread you. I think their reason for not
providing man pages is similar to their not providing the option I
asked for to not import "Inconsistent line end" formats. It's just
not in the direction they want to go.
> That may be so, but I still am mildly annoyed every time I type man
> FOO and get a "go use info" or worse, a URL. I'm at the command line
> or in EMACS a lot. Is it so wrong to want a concise reference within
> easy convenient reach? (Old habits die hard. I guess my virtual
> beard is showing.)
I was annoyed too, and I've only done UNIX/Linux since 1994 (not
saying I don't normally have a beard). I've been trying to get used
to looking first in info, so I'm less annoyed. I don't like info in
the shell, but in SUSE/KDE I press Alt-F2, run "##svn". Of course
then I was disappointed that it still gave no information except
referral, so I really should be complaining that they have avoided
man and info docs.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: Manual Pages
Posted by Nadav Har'El <ny...@math.technion.ac.il>.
On Wed, Jan 24, 2007, Jeff Smith wrote about "Re: Manual Pages":
> First of all, you said "someone *already* wrote such manual pages",
> but then you point to HTML pages. Do you not understand the
> difference between "man" and "HTML"?
Surely I understand... I've been using manual pages for 22 years, and HTML
for 13 years. There's no need to assume that I don't know what I'm talking
about :-)
What I said was that these HTML pages (which are ultimately generated from
docbook sources) contain exactly the kind of text that users expect
to find in a manpage, with exactly the sections that are expected. I never
tried to claim that these pages use Troff's "an" macros, or anything like
that.
> Ok I don't seriously think that
> nobody has made it into man page format, yet why would the subversion
> team need to maintain man page format when they already have
> automatically generating HTML help (which is ultimately better)?
Each of the documentations formats and styles you mentioned have their
advantages and disavantages, and we can debated them ad nauseam (I already
mentioned some of the man advantages in previous posts).
The point was that nobody needs to "maintain man page format" - I wanted it
to be completely automatic - just like the HTML and PDF gets created
automatically from the docbook sources, so can the man pages.
The big win would be that Unix/Linux users, which traditionally find these
manpages useful, will have them. I never tried to suggest that we should
drop the HTML pages.
> Further, you will find that for 10 years authors have been
> deprecating their `man` pages and generating more manageable formats,
> like `info`.
This debate is far from clear-cut. There are advantages to both styles
(these are not just file formats!) of documentation. Texinfo documentation
is best for long, book-like, with many sections, subsections, introduction,
and so on. Man pages are short references only for *shell commands* and
*C APIs* (for other things, like GUI programs, man pages won't work well,
and you must use something like texinfo or HTML). So each is appropriate for
different things.
The beautiful thing about the svnbook is that it already contains both
styles of documentation - it starts with a long detailed tutorial (of the
kind that sometimes appear in texinfo documentation), and ends with a
short but accurate reference for each of the shell commands - exactly of
the type that is normally found in man pages.
> Now I see that you are not even requesting to build "man" pages (after
> all, they wouldn't even work in MS Win). You are only saying that you
> don't think the docs are complete, or consolidated enough.
No way! That's not what I said! I think they are very complete, and just
wished that the sections which already look like man pages, could be made
into actual man pages which I could fetch with the "man" command, instead
of going through HTML links.
--
Nadav Har'El | Wednesday, Jan 24 2007, 5 Shevat 5767
nyh@math.technion.ac.il |-----------------------------------------
Phone +972-523-790466, ICQ 13349191 |Schroedinger's cat has 18 half-lives.
http://nadav.harel.org.il |
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: Manual Pages
Posted by "B. Smith-Mannschott" <be...@gmail.com>.
On 1/24/07, Jeff Smith <js...@robotronics.com> wrote:
> First of all, you said "someone *already* wrote such manual pages",
> but then you point to HTML pages. Do you not understand the
> difference between "man" and "HTML"?
Do you not understand the difference between HTML, and the and
DocBookXML sources it was generated from? (I'm afraid you set
yourself up for that retort.)
It seems a sprinkling of XSLT could transform the contents of
ch-reference.xml to a DocBook refentry [1], which could then be fed to
manpage.xsl [2] to produce a man page.
[1] http://www.docbook.org/tdg/en/html/refentry.html
[2] http://www.methods.co.nz/asciidoc/chunked/ar01s28.html
just sayin'
[...snip...]
> Further, you will find that for 10 years authors have been
> deprecating their `man` pages and generating more manageable formats,
> like `info`.
That may be so, but I still am mildly annoyed every time I type man
FOO and get a "go use info" or worse, a URL. I'm at the command line
or in EMACS a lot. Is it so wrong to want a concise reference within
easy convenient reach? (Old habits die hard. I guess my virtual beard
is showing.)
In the particular case of svn, I do find myself reflexively typeing
'man svn' only to my own irritation. It's not such a problem though
because "svn help" is detailed enough to be an adequate substitute in
most cases.
// Ben
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: Manual Pages
Posted by Jeff Smith <js...@robotronics.com>.
First of all, you said "someone *already* wrote such manual pages",
but then you point to HTML pages. Do you not understand the
difference between "man" and "HTML"? Ok I don't seriously think that
nobody has made it into man page format, yet why would the subversion
team need to maintain man page format when they already have
automatically generating HTML help (which is ultimately better)?
Further, you will find that for 10 years authors have been
deprecating their `man` pages and generating more manageable formats,
like `info`.
[more below]
On Wednesday 24 January 2007 04:45, Nadav Har'El wrote:
> The example that bothered me was the "info" command. Compare "svn
> help info" to http://svnbook.red-bean.com/en/1.1/re13.html
>
> "svn help info" is way too short and is missing a lot of
> information. What kinds of details can "svn info" print? Does it
> access the repository, or just the working files? All this
> information (and no useless "cruft") is in the aforementioned Web
> page, which could make a very good manpage, so why not?
>
> Other pages on the svnbook site have different advantages over the
> corresponding "svn help" result. Some have examples of typical
> usage, information on what happens in exceptional cases, and more.
Now I see that you are not even requesting to build "man" pages (after
all, they wouldn't even work in MS Win). You are only saying that you
don't think the docs are complete, or consolidated enough.
I rely on the svnbook. Sorry to burst your bubble but I don't think
you're the only one who knew about
http://svnbook.red-bean.com/
And yes, it IS the recommended reading to _learn_ svn. Then the `svn
help` stuff is for reference, if you need a little nudge, for example
to remember the syntaxt of `svn import [...]`
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: Manual Pages
Posted by Adrian Howard <ad...@quietstars.com>.
On 24 Jan 2007, at 11:15, Nadav Har'El wrote:
> Hi, I've been wondering why the Subversion commands do not have manual
> pages. Why can't I run "man svn" or "man svn-checkout" and expect
> to see
> something useful?
[snip]
Is there anything that man pages would give you that
svk help <command>
wouldn't?
Adrian
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org