You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Blair Zajac <bl...@orcaware.com> on 2002/07/23 19:51:18 UTC
Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
sussman@tigris.org wrote:
>
> Author: sussman
> Date: Tue, 23 Jul 2002 14:30:12 -0500
> New Revision: 2653
>
> Modified:
> trunk/doc/handbook/appendices.texi
> trunk/doc/handbook/client.texi
> trunk/doc/handbook/getting_started.texi
> trunk/doc/handbook/outline.txt
> trunk/doc/handbook/repos_admin.texi
> trunk/www/subversion-diagram.png
Ben,
Is the handbook open for commits?
I noticed that there's inconsistent usage of @file, @samp and @url
throughout the document with different people using different
standards, i.e., file's are mentioned but not placed in @file{},
other @samp's enclose sample URLs that could be changed to @url,
etc.
Is this worth changing to get consistent?
Blair
--
Blair Zajac <bl...@orcaware.com>
Web and OS performance plots - http://www.orcaware.com/orca/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
Posted by Josef Wolf <jw...@raven.inka.de>.
On Fri, Jul 26, 2002 at 08:07:07PM -0500, Karl Fogel wrote:
> > Why should our handbook explain RFCs? People can read RFCs themselves.
> The handbook exists to help people understand. If lots of people are
> not understanding, then it's not a question of whether they've been
> "responsible" and done their homework -- it's a question of *helping
> them understand*. :-)
Thanks, Karl. That was exactly what I tried to express, but as english
is not my native language, it is not easy to find such good words :)
> Another way to think of it is: Subversion may be exposing many more
> people to the "file:///" convention than were previously exposed to it
Most people in the windows-world don't even _know_ about the file:///
style. Worse: most people in the windows-world don't know that a thing
named "RFC" even _exists_.
> (especially considering that browsers compensate for missing slashes).
Hmmm, maybe svn could compensate, tooo? Please don't flame me for that
suggestion ;-)
> But *we* are able to anticipate their need for information, so we
> should supply that information.
Yes, the less the hurdle to join the subversion world, the more
are the chances that people will actually switch to svn.
--
-- Josef Wolf -- jw@raven.inka.de --
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Branko Čibej <br...@xbc.nu> writes:
> >Hmm, so file://localhost/foo/bar should do the work, too?
>
> Yes, and in fact Subversion allows that form.
>
> >I think an accurate statement in the handbook could avoid confusion.
>
> Why should our handbook explain RFCs? People can read RFCs themselves.
The handbook exists to help people understand. If lots of people are
not understanding, then it's not a question of whether they've been
"responsible" and done their homework -- it's a question of *helping
them understand*. :-)
Another way to think of it is: Subversion may be exposing many more
people to the "file:///" convention than were previously exposed to it
(especially considering that browsers compensate for missing slashes).
So if we're going to expand their experience like that, we need to
document the new territory too. Expecting them to read the RFC is no
good -- how would they know which one to read, or even to look in an
RFC?
But *we* are able to anticipate their need for information, so we
should supply that information. We can do it as an unobtrusive
reference to the rfc, or just explain the deal as a quick footnote, or
whatever works best. But we shouldn't just say "That's not our
bailiwick" and ignore the issue.
I've devoted more space to this response than might be expected,
because similar questions are going to come up, and I wanted to
articulate the general philosophy early. I'm not saying we should
document everything in the world -- just those things that Subversion
exposes people to for the first time. That includes (obviously)
Subversion itself, but it also may include other things that are not
strictly part of Subversion, but are associated with it.
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
Posted by Branko Čibej <br...@xbc.nu>.
Josef Wolf wrote:
>On Fri, Jul 26, 2002 at 06:07:20PM -0500, Ben Collins-Sussman wrote:
>
>>Another way people look at it: the nonexistent hostname would
>>normally go between the 2nd and 3rd slash.
>>
>>
>
>Hmm, so file://localhost/foo/bar should do the work, too?
>
Yes, and in fact Subversion allows that form.
>I think an accurate statement in the handbook could avoid confusion.
>
Why should our handbook explain RFCs? People can read RFCs themselves.
--
Brane Čibej <br...@xbc.nu> http://www.xbc.nu/brane/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
Posted by Josef Wolf <jw...@raven.inka.de>.
On Fri, Jul 26, 2002 at 06:07:20PM -0500, Ben Collins-Sussman wrote:
> Josef Wolf <jw...@raven.inka.de> writes:
> > I second this :). There is just one thing i _still_ don't understand
> > and can't find any documentation: why do the file:///foo style of
> > URLs require _three_ slashes?
>
> We didn't make that up. Standard rfc's dictate that url schemas always
> look like "schema://". And the file:// schema requires that an
> absolute path follow, hence file:///absolute/path.
Thanks for the answer, but my point was that this should be explained
somewhere in the _handbook_. As I mentioned in my original post, I was
already on the path to get used to it :)
> Another way people look at it: the nonexistent hostname would
> normally go between the 2nd and 3rd slash.
Hmm, so file://localhost/foo/bar should do the work, too? I think an
accurate statement in the handbook could avoid confusion.
--
-- Josef Wolf -- jw@raven.inka.de --
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
Posted by Ben Collins-Sussman <su...@collab.net>.
Josef Wolf <jw...@raven.inka.de> writes:
> On Tue, Jul 23, 2002 at 07:15:36PM -0400, Garrett Rooney wrote:
> > On Tue, Jul 23, 2002 at 03:00:14PM -0500, Ben Collins-Sussman wrote:
>
> > other than that, it looks fantastic, and is a good intro for our soon
> > to be hordes of users ;-)
>
> I second this :). There is just one thing i _still_ don't understand
> and can't find any documentation: why do the file:///foo style of
> URLs require _three_ slashes?
We didn't make that up. Standard rfc's dictate that url schemas always
look like "schema://". And the file:// schema requires that an
absolute path follow, hence file:///absolute/path.
Another way people look at it: the nonexistent hostname would
normally go between the 2nd and 3rd slash.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
On Sat, Jul 27, 2002 at 01:01:29AM +0200, Josef Wolf wrote:
> On Tue, Jul 23, 2002 at 07:15:36PM -0400, Garrett Rooney wrote:
> > On Tue, Jul 23, 2002 at 03:00:14PM -0500, Ben Collins-Sussman wrote:
>
> > other than that, it looks fantastic, and is a good intro for our soon
> > to be hordes of users ;-)
>
> I second this :). There is just one thing i _still_ don't understand
> and can't find any documentation: why do the file:///foo style of
> URLs require _three_ slashes? It seems to me that it has to do with
> absolute/relative paths, but I cant find any docu. I think one or two
> sentences about this topic could avoid a lot of confision.
that's what a file:// url looks like. the file:// part is the "i'm a
local file url indicator" and the /foo part is an absolute path from
the root of the filesystem to the file. so you put them together and
you get file:///foo. think about what you'd have if you took the host
part out of the http://foo.com/bar url and you'll see it's the same
thing.
-garrett
--
garrett rooney Remember, any design flaw you're
rooneg@electricjellyfish.net sufficiently snide about becomes
http://electricjellyfish.net/ a feature. -- Dan Sugalski
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
Posted by Daniel Rall <dl...@finemaltcoding.com>.
Josef Wolf <jw...@raven.inka.de> writes:
> On Tue, Jul 23, 2002 at 07:15:36PM -0400, Garrett Rooney wrote:
> > On Tue, Jul 23, 2002 at 03:00:14PM -0500, Ben Collins-Sussman wrote:
>
> > other than that, it looks fantastic, and is a good intro for our soon
> > to be hordes of users ;-)
>
> I second this :). There is just one thing i _still_ don't understand
> and can't find any documentation: why do the file:///foo style of
> URLs require _three_ slashes? It seems to me that it has to do with
> absolute/relative paths, but I cant find any docu. I think one or two
> sentences about this topic could avoid a lot of confision.
Mozilla works with one slash for file URLs, but does this by
converting it to three slashes.
file:/home/dlr -> file:///home/dlr
--
Daniel Rall <dl...@finemaltcoding.com>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
Posted by Josef Wolf <jw...@raven.inka.de>.
On Tue, Jul 23, 2002 at 07:15:36PM -0400, Garrett Rooney wrote:
> On Tue, Jul 23, 2002 at 03:00:14PM -0500, Ben Collins-Sussman wrote:
> other than that, it looks fantastic, and is a good intro for our soon
> to be hordes of users ;-)
I second this :). There is just one thing i _still_ don't understand
and can't find any documentation: why do the file:///foo style of
URLs require _three_ slashes? It seems to me that it has to do with
absolute/relative paths, but I cant find any docu. I think one or two
sentences about this topic could avoid a lot of confision.
--
-- Josef Wolf -- jw@raven.inka.de --
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Patch for blank pages in svn-handbook Was: Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
Posted by Ben Collins-Sussman <su...@collab.net>.
Russell Steicke <ru...@arach.net.au> writes:
> On Tue, Jul 23, 2002 at 07:15:36PM -0400, Garrett Rooney wrote:
> ...
> > does anyone else see a bunch of random blank pages in the pdf and ps
> > versions? specifically pages 1 and 2 seem to come out blank every
> > time for me... just seems weird, and i don't know enough texinfo to
> > say where they are coming from...
>
> Here's a patch to fix that. Dunno who to send this to, I hope the list
> doesn't mind.
>
> Index: ./svn-handbook.texi
> ===================================================================
> --- ./svn-handbook.texi
> +++ ./.svn/tmp/svn-handbook.texi.60860.00001.tmp Wed Jul 24 23:14:37 2002
> @@ -84,10 +84,10 @@
> @summarycontents
> @contents
>
> -@node Top
> -@top
>
> @ifinfo
> +@node Top
> +@top
> This manual is a general guide to the Subversion revision control system.
Thanks! This fixes the blank pages produced by texi2dvi.
I'm applying this patch, slightly changed: the @ifinfo needs to
become @ifnottex. Otherwise 'makeinfo --html' complains.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Patch for blank pages in svn-handbook Was: Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
Posted by Russell Steicke <ru...@arach.net.au>.
On Tue, Jul 23, 2002 at 07:15:36PM -0400, Garrett Rooney wrote:
...
> does anyone else see a bunch of random blank pages in the pdf and ps
> versions? specifically pages 1 and 2 seem to come out blank every
> time for me... just seems weird, and i don't know enough texinfo to
> say where they are coming from...
Here's a patch to fix that. Dunno who to send this to, I hope the list
doesn't mind.
> other than that, it looks fantastic, and is a good intro for our soon
> to be hordes of users ;-)
One of whom is me! The handbook looks good,
Russell
Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
On Tue, Jul 23, 2002 at 03:00:14PM -0500, Ben Collins-Sussman wrote:
> Definitely! This is the big risk of allowing many, many people to
> patch it. Well, not really a "risk", but yes, we should be reviewing
> those commits more carefully, trying to ensure consistent tag style.
> Just as we have a coding style, we should make sure people are using
> texinfo tags consistenly as well.
>
> Please fix the problems you see... your points above are definitely
> things worth fixing.
just picking a random handbook related thread to respond to...
does anyone else see a bunch of random blank pages in the pdf and ps
versions? specifically pages 1 and 2 seem to come out blank every
time for me... just seems weird, and i don't know enough texinfo to
say where they are coming from...
other than that, it looks fantastic, and is a good intro for our soon
to be hordes of users ;-)
-garrett
--
garrett rooney Remember, any design flaw you're
rooneg@electricjellyfish.net sufficiently snide about becomes
http://electricjellyfish.net/ a feature. -- Dan Sugalski
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn commit: rev 2653 - trunk/www trunk/doc/handbook
Posted by Ben Collins-Sussman <su...@collab.net>.
Blair Zajac <bl...@orcaware.com> writes:
> Is the handbook open for commits?
Absolutely. I was a bit zealous about getting the "first draft" done
by just one or two people, for consistency and readablity. But I have
no more pending changes. At this point, we should treat it like
open source code. It should change as subversion changes.
> I noticed that there's inconsistent usage of @file, @samp and @url
> throughout the document with different people using different
> standards, i.e., file's are mentioned but not placed in @file{},
> other @samp's enclose sample URLs that could be changed to @url,
> etc.
>
> Is this worth changing to get consistent?
Definitely! This is the big risk of allowing many, many people to
patch it. Well, not really a "risk", but yes, we should be reviewing
those commits more carefully, trying to ensure consistent tag style.
Just as we have a coding style, we should make sure people are using
texinfo tags consistenly as well.
Please fix the problems you see... your points above are definitely
things worth fixing.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org