You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Ben Collins-Sussman <su...@collab.net> on 2002/07/17 14:44:15 UTC
svn documentation
Hi all... in case you didn't notice my checkin last night, the first
draft of the Subversion Handbook is done. Everyone, please feel free
to proofread it, check for spelling & grammar errors, etc. I want
this document to be the "main" documentation that ships in the
Subversion tree, which is why all the old docs have suddenly
disappeared. The Handbook is all we have to go on until,
well... until a certain O'Reilly book is released. :-)
If you maintain some kind of Subversion distribution (RPM, .deb, BSD
port), please try to install the Handbook on the system, preferably as
'info'.
Also, while I have your attention, I'd love it if some texinfo expert
could look at two problems I'm having:
1. My version of 'texi2html' doesn't seem to understand the
@command{} tag at all; this makes the HTML output pretty
unreadable, as this tag is used all over the docs.
2. When I run 'texi2dvi', I get no table of contents at the
beginning, not sure why. I'd like to use dvips to put up a nice
postscript doc with a TOC.
Any ideas?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn documentation
Posted by Féliciano Matias <fe...@free.fr>.
Le mer 17/07/2002 à 16:44, Ben Collins-Sussman a écrit :
>
> Hi all... in case you didn't notice my checkin last night, the first
> draft of the Subversion Handbook is done. Everyone, please feel free
> to proofread it, check for spelling & grammar errors, etc. I want
> this document to be the "main" documentation that ships in the
> Subversion tree, which is why all the old docs have suddenly
> disappeared. The Handbook is all we have to go on until,
> well... until a certain O'Reilly book is released. :-)
>
Sorry for my poor english.
I do a traslation in french of your "beautiful" handbook.
My translation correspond to the revision 2610 of Subversion.
I don't translate the License term witch is critical.
See the attachment for a diff against revision 2638.
One critical of the handbook :
* in repos_admin.texi (@node Networking a repository)
You recommend to add "ServerName svn.myserver.org" in httpd.conf file.
I think this is useless if "UseCanonicalName Off" is define in the
httpd.conf file.
UseCanonicalName :
# URLs and the SERVER_NAME and SERVER_PORT variables.
# When set "Off", Apache will use the Hostname and Port supplied
# by the client. When set "On", Apache will use the value of the
# ServerName directive.
I found "UseCanonicalName Off" better than "ServerName
svn.myserver.org".
For exemple, my repository in my computer is available with :
http://127.0.0.1/svn/repos/myrepos
http://localhost/svn/repos/myrepos
http://myhostname/svn/repos/myrepos
without any troubles. This is also better with complex rewriterule
redirection and work also fine with virtual named hosting.
Re: svn documentation
Posted by Ben Collins-Sussman <su...@collab.net>.
Greg Stein <gs...@lyra.org> writes:
> > Everyone, please feel free
> > to proofread it, check for spelling & grammar errors, etc. I want
> > this document to be the "main" documentation that ships in the
> > Subversion tree, which is why all the old docs have suddenly
> > disappeared. The Handbook is all we have to go on until,
> > well... until a certain O'Reilly book is released. :-)
>
> Euh. I suspect you didn't mean this, but to be clear: we don't really want
> to rely on documentation people have to *pay* to get. Subversion will always
> need its own doc.
The O'Reilly book will have a Free license and be on-line when
finished. Many of their books are like that, actually.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn documentation
Posted by Greg Stein <gs...@lyra.org>.
On Wed, Jul 17, 2002 at 09:44:15AM -0500, Ben Collins-Sussman wrote:
>
> Hi all... in case you didn't notice my checkin last night, the first
> draft of the Subversion Handbook is done.
Woo! Great work!
> Everyone, please feel free
> to proofread it, check for spelling & grammar errors, etc. I want
> this document to be the "main" documentation that ships in the
> Subversion tree, which is why all the old docs have suddenly
> disappeared. The Handbook is all we have to go on until,
> well... until a certain O'Reilly book is released. :-)
Euh. I suspect you didn't mean this, but to be clear: we don't really want
to rely on documentation people have to *pay* to get. Subversion will always
need its own doc.
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn documentation
Posted by Ben Collins-Sussman <su...@collab.net>.
Russ Allbery <rr...@stanford.edu> writes:
> Jostein Christoffer Andersen <jo...@josander.net> writes:
> > On onsdag 17 juli 2002, 16.44, Ben Collins-Sussman wrote:
>
> >> Also, while I have your attention, I'd love it if some texinfo expert
> >> could look at two problems I'm having:
>
> >> 1. My version of 'texi2html' doesn't seem to understand the
> >> @command{} tag at all; this makes the HTML output pretty
> >> unreadable, as this tag is used all over the docs.
>
> >> Any ideas?
>
> > It's the texi2html perl program who don't understand it.
>
> > I use the following Perl oneliner to correct this after texi2html have
> > done it's job:
>
> > perl -pi -e 's/\@command\{(.*)\}/<KBD>$1<\/KBD>/g' /path_to/*.html
>
> Alternately, you can just upgrade texi2html. 1.64 seems to understand
> @command without any trouble.
I've abandoned texi2html altogether. Apparently the FSF doesn't want
any more texi2foo scripts circulating anymore; instead, it wants
people to concentrate on building & improving the filters within
'makeinfo'.
So now I run 'makeinfo --html' instead. So does our 'make doc'
target.
(*) The only exception to this rule, apparently, is 'texi2dvi'.
That's the only script sanctioned by the FSF.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn documentation
Posted by Russ Allbery <rr...@stanford.edu>.
Jostein Christoffer Andersen <jo...@josander.net> writes:
> On onsdag 17 juli 2002, 16.44, Ben Collins-Sussman wrote:
>> Also, while I have your attention, I'd love it if some texinfo expert
>> could look at two problems I'm having:
>> 1. My version of 'texi2html' doesn't seem to understand the
>> @command{} tag at all; this makes the HTML output pretty
>> unreadable, as this tag is used all over the docs.
>> Any ideas?
> It's the texi2html perl program who don't understand it.
> I use the following Perl oneliner to correct this after texi2html have
> done it's job:
> perl -pi -e 's/\@command\{(.*)\}/<KBD>$1<\/KBD>/g' /path_to/*.html
Alternately, you can just upgrade texi2html. 1.64 seems to understand
@command without any trouble.
--
Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn documentation
Posted by Jostein Christoffer Andersen <jo...@josander.net>.
On onsdag 17 juli 2002, 16.44, Ben Collins-Sussman wrote:
> Also, while I have your attention, I'd love it if some texinfo expert
> could look at two problems I'm having:
>
> 1. My version of 'texi2html' doesn't seem to understand the
> @command{} tag at all; this makes the HTML output pretty
> unreadable, as this tag is used all over the docs.
> Any ideas?
It's the texi2html perl program who don't understand it.
I use the following Perl oneliner to correct this after texi2html have
done it's job:
perl -pi -e 's/\@command\{(.*)\}/<KBD>$1<\/KBD>/g' /path_to/*.html
Jostein
--
----------------------------------------------------------------------
Jostein Christoffer Andersen <jo...@josander.net>
http://www.josander.net/
Public PGP Key:
Key: http://www.josander.net/pub_keys/jostein_josander.net.asc
----------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn documentation
Posted by Josef Wolf <jw...@raven.inka.de>.
On Wed, Jul 17, 2002 at 07:23:47PM -0700, Peter Davis wrote:
> * What happened to the 'http://foo/svn/.../@rev' syntax? Did that
> get removed? I thought it was kind of nice :) In any case, an
> explaination of how URL's work with Subversion (both http:// and
> file://), especially how the left hand part specifies the path to
> the repository and the right hand part is the node within the
> repository, but the division between the two is not usually
> apparent. Maybe this is obvious.
While at it: when I created my first repo I found it very confusing
that svnadmin and svnlook take a path and not an URL. The reasons for
file:///path needing three slashes should be mentioned in the
handbook, too.
--
-- 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 documentation
Posted by Ben Collins-Sussman <su...@collab.net>.
Peter Davis <pe...@pdavis.cx> writes:
> I had no idea you had been writing such an excellent piece of
> documentation! Other projects would be proud to have such a
> handbook.
Sir, you make my head swell. :-)
> * In section 3.5, you talk about writing a Perl script to crypt(3) passwords
> for Apache's access control. I find it much easier to use the htpasswd
> command that is installed in /path/to/apache/bin/htpasswd:
>
> $ /path/to/apache/bin/htpasswd /path/to/passwd/file username
> New password: [password]
> Re-type new password: [password]
> Adding password for user username
>
> Hopefully this would be a little less intimidating to non-Perl users.
Oh wow, great idea. I totally forgot about htpasswd. I definitely
swap that in instead of the perl script.
> * Of course I personally know all about branches and tags (Section
> 2.4) and their use-cases, since they are such an integral part of
> most version control systems, but newbies may not. If you don't
> want to spend time reproducing what many others have already written
> (or maybe this handbook is just not aimed at total newbies?),
Actually, I'd like to think that "total newbies to version control"
can still understand this document... although I suppose the document
*does* assume that you are a basic Unix-user.
I'll see if I can fill this hole with a link or explanation...
> * What happened to the 'http://foo/svn/.../@rev' syntax? Did that get
> removed? I thought it was kind of nice :)
No, it's still around, but '-r N' is easier to introduce. I figure
the URL@N syntax can be discovered later on when people run "svn help
diff" or "svn help merge".
> In any case, an explaination of how URL's work with Subversion
> (both http:// and file://), especially how the left hand part
> specifies the path to the repository and the right hand part is the
> node within the repository, but the division between the two is not
> usually apparent. Maybe this is obvious.
No, maybe it isn't actually... that's a good point!
> On a related note, in your first example of using 'svnadmin create
> myrepos', it isn't clear what exactly 'myrepos' is supposed to be.
> It is a directory of course, but it might be helpful to show the
> example (and other examples using 'myrepos') using a full path like
> '/path/to/myrepos', just to show that myrepos is actually created as
> a directory on the disk, and is not just some magical identifier.
> Also consider pointing out that '/path/to' has to exist beforehand.
Ah, yes, sure.
Thanks for the feedback!
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: svn documentation
Posted by Peter Davis <pe...@pdavis.cx>.
I had no idea you had been writing such an excellent piece of documentation!
Other projects would be proud to have such a handbook. A few comments:
* In section 3.5, you talk about writing a Perl script to crypt(3) passwords
for Apache's access control. I find it much easier to use the htpasswd
command that is installed in /path/to/apache/bin/htpasswd:
$ /path/to/apache/bin/htpasswd /path/to/passwd/file username
New password: [password]
Re-type new password: [password]
Adding password for user username
Hopefully this would be a little less intimidating to non-Perl users.
* Of course I personally know all about branches and tags (Section 2.4) and
their use-cases, since they are such an integral part of most version control
systems, but newbies may not. If you don't want to spend time reproducing
what many others have already written (or maybe this handbook is just not
aimed at total newbies?), please provide a pointer to the Cederqvist (sp?)
book or somewhere else that has a newbie-oriented explaination as to why/how
branches and tags should be used and managed in the first place.
* What happened to the 'http://foo/svn/.../@rev' syntax? Did that get
removed? I thought it was kind of nice :) In any case, an explaination of
how URL's work with Subversion (both http:// and file://), especially how the
left hand part specifies the path to the repository and the right hand part
is the node within the repository, but the division between the two is not
usually apparent. Maybe this is obvious.
On a related note, in your first example of using 'svnadmin create myrepos',
it isn't clear what exactly 'myrepos' is supposed to be. It is a directory
of course, but it might be helpful to show the example (and other examples
using 'myrepos') using a full path like '/path/to/myrepos', just to show that
myrepos is actually created as a directory on the disk, and is not just some
magical identifier. Also consider pointing out that '/path/to' has to exist
beforehand.
Hopefully none of the additions I request are too obvious. I'm trying to read
this as though I had never used Subversion or CVS before. Of course you
can't expect my grandmother to read this and know what to do, but maybe a
disclaimer at the top saying "The examples that follow require at least
minimal knowledge of a UNIX command line, blah blah... If you are using
Windows, remember to use '\' instead of '/' as path separators, blah
blah...".
Thanks!
--
Peter Davis
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
RE: svn documentation
Posted by Mats Nilsson <ma...@xware.se>.
A few comments regarding the documentation.
In section 1.4.2.2, the file path in the 'svn co' command doesn't quite
agree with the preceeding example, and the text below the command is also
refering to myproj, which is missing in the path.
In section 2.2.3, when 'svn st' is discussed, status code '?' is described,
but not '!', contrary to what is promised in the text.
It would be nice to have the revision short-cuts HEAD, BASE, PREV (others?)
explained somewhere.
/Mats
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: SV: svn documentation
Posted by Ben Collins-Sussman <su...@collab.net>.
Thanks! I'll fix that.
"Morten Ludvigsen" <mo...@2ps.dk> writes:
> Hi,
>
> I downloaded the handbook from the home page yesterday (danish time) in
> .ps-format. I have read it through, and I think it is a great doc. I only
> came across one thing that did not make sense. On page 32 in the section
> about "svn mkdir" it says: "Or, it can be used to instantly delete a file or
> directory from a repository...". It should propably say: "Or, it can be used
> to instantly create a directory in a repository...".
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
SV: svn documentation
Posted by Morten Ludvigsen <mo...@2ps.dk>.
Hi,
I downloaded the handbook from the home page yesterday (danish time) in
.ps-format. I have read it through, and I think it is a great doc. I only
came across one thing that did not make sense. On page 32 in the section
about "svn mkdir" it says: "Or, it can be used to instantly delete a file or
directory from a repository...". It should propably say: "Or, it can be used
to instantly create a directory in a repository...".
Regards,
Morten Ludvigsen
> -----Oprindelig meddelelse-----
> Fra: sussman@collab.net [mailto:sussman@collab.net]
> Sendt: 17. juli 2002 16:44
> Til: SVN Dev List
> Emne: svn documentation
>
>
>
> Hi all... in case you didn't notice my checkin last night, the first
> draft of the Subversion Handbook is done. Everyone, please feel free
> to proofread it, check for spelling & grammar errors, etc. I want
> this document to be the "main" documentation that ships in the
> Subversion tree, which is why all the old docs have suddenly
> disappeared. The Handbook is all we have to go on until,
> well... until a certain O'Reilly book is released. :-)
>
> If you maintain some kind of Subversion distribution (RPM, .deb, BSD
> port), please try to install the Handbook on the system, preferably as
> 'info'.
>
> Also, while I have your attention, I'd love it if some texinfo expert
> could look at two problems I'm having:
>
> 1. My version of 'texi2html' doesn't seem to understand the
> @command{} tag at all; this makes the HTML output pretty
> unreadable, as this tag is used all over the docs.
>
> 2. When I run 'texi2dvi', I get no table of contents at the
> beginning, not sure why. I'd like to use dvips to put up a nice
> postscript doc with a TOC.
>
> Any ideas?
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
> For additional commands, e-mail: dev-help@subversion.tigris.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org