patch for documentation about version control

patch for documentation about version control

[Alex Ott]

[-- Attachment #1: Type: text/plain, Size: 81 bytes --]

Hi all

this patch add some docs about version control systems supported by vc.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: emacs-man-files.text.diff --]
[-- Type: text/x-patch, Size: 3220 bytes --]

Index: man/files.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/files.texi,v
retrieving revision 1.91
diff -u -w -b -B -r1.91 files.texi
--- man/files.texi	9 Oct 2004 18:41:18 -0000	1.91
+++ man/files.texi	9 Nov 2004 06:57:21 -0000
@@ -1119,11 +1119,12 @@
 description of what was changed in that version.
 
   The Emacs version control interface is called VC.  Its commands work
-with three version control systems---RCS, CVS, and SCCS.  The GNU
-project recommends RCS and CVS, which are free software and available
-from the Free Software Foundation.  We also have free software to
-replace SCCS, known as CSSC; if you are using SCCS and don't want to
-make the incompatible change to RCS or CVS, you can switch to CSSC.
+with different version control systems---RCS, CVS, SCCS, Meta-CVS, GNU
+Arch and Subversion.  The GNU project recommends RCS, CVS, and GNU Arch
+which are free software and available from the Free Software Foundation.
+We also have free software to replace SCCS, known as CSSC; if you are
+using SCCS and don't want to make the incompatible change to RCS or CVS,
+you can switch to CSSC.
 
   VC is enabled by default in Emacs.  To disable it, set the
 customizable variable @code{vc-handled-backends} to @code{nil}
@@ -1166,8 +1167,9 @@
 
 @cindex RCS
 @cindex back end (version control)
-  VC currently works with three different version control systems or
-``back ends'': RCS, CVS, and SCCS.
+  VC currently works with six different version control systems or
+``back ends'': RCS, CVS, SCCS, MCVS (Meta-CVS), Arch (GNU Arch) and SVN
+(Subversion).
 
   RCS is a free version control system that is available from the Free
 Software Foundation.  It is perhaps the most mature of the supported
@@ -1190,6 +1192,33 @@
 features, such as multiple branches, are not available with SCCS.  You
 should use SCCS only if for some reason you cannot use RCS.
 
+@cindex MCVS
+@cindex Meta-CVS
+
+Meta-CVS is another attempt to solve problems, arising in CVS.  It
+supports directory structure versioning, improved branching and merging,
+and use of symbolic links and meta-data in repositories.
+
+@cindex GNU Arch
+@cindex Arch
+  GNU Arch is new version control system that designed for distributed
+work.  It differs in many ways from old well-known systems, such as CVS
+and RCS.  It supports different transports for interoperating between
+users, offline operations and have good branching and merging features.
+It also supports atomic commits, and history of file renaming and
+moving.  VC supports not all operations, provided by GNU Arch, so you
+can call their from command line, or use specialized module.
+
+@cindex SVN
+@cindex Subversion
+  Subversion is version control system, that was designed for eliminate
+problems, that arrive with CVS usage, such as nonatomic commits, and
+losing history of file with renaming or moving file.  It also could be
+used via http or other standard protocols.  SVN has almost same concepts
+as CVS, but solve some problems.  Switching from CVS to SVN is very
+easy---just use @command{svn} command instead @command{cvs}.
+
+
 @node VC Concepts
 @subsubsection Concepts of Version Control
 

[-- Attachment #3: Type: text/plain, Size: 125 bytes --]



-- 
With best wishes, Alex Ott
Jet Infosystems,       http://www.jetinfosoft.ru/
                       +7 (095) 411 76 01

[-- Attachment #4: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: patch for documentation about version control

[Andre Spiegel]

On Tue, 2004-11-09 at 09:55 +0300, Alex Ott wrote:

> this patch add some docs about version control systems supported by vc.

Thanks, this is much appreciated.  I will put it in.

The records at the FSF seem to indicate that you've assigned copyright
for all future changes to the Emacs manual to the FSF, is that correct?

RMS, can you confirm this?  (The entry in copyright.list is not entirely
clear about it.)

Re: patch for documentation about version control

[Alex Ott]

>>>>> "AS" == Andre Spiegel writes:
 AS> On Tue, 2004-11-09 at 09:55 +0300, Alex Ott wrote:
 >> this patch add some docs about version control systems supported by vc.

 AS> Thanks, this is much appreciated.  I will put it in.

 AS> The records at the FSF seem to indicate that you've assigned copyright
 AS> for all future changes to the Emacs manual to the FSF, is that
 AS> correct?

yes - i assigned copyright for all changes

 AS> RMS, can you confirm this?  (The entry in copyright.list is not
 AS> entirely clear about it.)




-- 
With best wishes, Alex Ott
Jet Infosystems,       http://www.jetinfosoft.ru/
                       +7 (095) 411 76 01

Re: patch for documentation about version control

[Karl Fogel]

Alex Ott <ott@jet.msk.su> writes:
> this patch add some docs about version control systems supported by vc.
> 
> Index: man/files.texi
> ===================================================================
> RCS file: /cvsroot/emacs/emacs/man/files.texi,v
> retrieving revision 1.91
> diff -u -w -b -B -r1.91 files.texi
> --- man/files.texi	9 Oct 2004 18:41:18 -0000	1.91
> +++ man/files.texi	9 Nov 2004 06:57:21 -0000
> @@ -1119,11 +1119,12 @@
>  description of what was changed in that version.
>  
>    The Emacs version control interface is called VC.  Its commands work
> -with three version control systems---RCS, CVS, and SCCS.  The GNU
> -project recommends RCS and CVS, which are free software and available
> -from the Free Software Foundation.  We also have free software to
> -replace SCCS, known as CSSC; if you are using SCCS and don't want to
> -make the incompatible change to RCS or CVS, you can switch to CSSC.
> +with different version control systems---RCS, CVS, SCCS, Meta-CVS, GNU
> +Arch and Subversion.  The GNU project recommends RCS, CVS, and GNU Arch
> +which are free software and available from the Free Software Foundation.
> +We also have free software to replace SCCS, known as CSSC; if you are
> +using SCCS and don't want to make the incompatible change to RCS or CVS,
> +you can switch to CSSC.

Minor nit: from this sentence

   "The GNU project recommends RCS, CVS, and GNU Arch which are
    free software...",

some readers could mistakenly infer that the other systems are *not*
free software.  And because of that lead-in, the next sentence about a
free replacement for SCCS only strengthens the misimpression.

Since Subversion and Meta-CVS are both free software, could this
paragraph be tweaked?  Here's one possible rewording:

     The Emacs version control interface is called VC.  Its commands work
   with different version control systems---RCS, CVS, SCCS, Meta-CVS, GNU
   Arch and Subversion.  The GNU project recommends and distributes
   RCS, CVS, and GNU Arch.  We also have free software to replace
   SCCS, known as CSSC; if you are using SCCS and don't want to make
   the incompatible change to RCS or CVS, you can switch to CSSC.

Also, I was looking at the rest of the patch, and saw a few grammar
problems:

> @@ -1190,6 +1192,33 @@
>  features, such as multiple branches, are not available with SCCS.  You
>  should use SCCS only if for some reason you cannot use RCS.
>  
> +@cindex MCVS
> +@cindex Meta-CVS
> +
> +Meta-CVS is another attempt to solve problems, arising in CVS.  It
> +supports directory structure versioning, improved branching and merging,
> +and use of symbolic links and meta-data in repositories.

s/solve problems, arising in/solve the problems of/

> +@cindex GNU Arch
> +@cindex Arch
> +  GNU Arch is new version control system that designed for distributed
> +work.  It differs in many ways from old well-known systems, such as CVS
> +and RCS.  It supports different transports for interoperating between
> +users, offline operations and have good branching and merging features.
> +It also supports atomic commits, and history of file renaming and
> +moving.  VC supports not all operations, provided by GNU Arch, so you
> +can call their from command line, or use specialized module.

This had a few problems, so here's a rewrite:

  +  GNU Arch is new version control system that is designed for distributed
  +work.  It differs in many ways from old well-known systems, such as CVS
  +and RCS.  It supports different transports for interoperating between
  +users, offline operations, and it has good branching and merging features.
  +It also supports atomic commits, and history of file renaming and
  +moving.  VC does not support all operations provided by GNU Arch, so you
  +can invoke it from the command line, or use a specialized module.

> +@cindex SVN
> +@cindex Subversion
> +  Subversion is version control system, that was designed for eliminate
> +problems, that arrive with CVS usage, such as nonatomic commits, and
> +losing history of file with renaming or moving file.  It also could be
> +used via http or other standard protocols.  SVN has almost same concepts
> +as CVS, but solve some problems.  Switching from CVS to SVN is very
> +easy---just use @command{svn} command instead @command{cvs}.

A few problems here too, both in grammar and content, so here's a
rewrite:

  +  Subversion is a version control system designed to be similar to CVS
  +but without CVS's problems.  Subversion supports atomic commits,
  +and versions directories, symbolic links, meta-data, renames, copies,
  +and deletes.  It can be used via http or via its own protocol.

By the way, is there any reason not to refer to the respective home
pages of these systems?  They are:

   Meta-CVS:    http://users.footprints.net/~kaz/mcvs.html
   GNU Arch:    http://www.gnu.org/software/gnu-arch/
   Subversion:  http://subversion.tigris.org/

Hope this helps, and thanks for writing the new content!

-Karl

Re: patch for documentation about version control

[Stefan Monnier]

> Minor nit: from this sentence

>    "The GNU project recommends RCS, CVS, and GNU Arch which are
>     free software...",

> some readers could mistakenly infer that the other systems are *not*
> free software.  And because of that lead-in, the next sentence about a
> free replacement for SCCS only strengthens the misimpression.

> Since Subversion and Meta-CVS are both free software, could this
> paragraph be tweaked?  Here's one possible rewording:

>      The Emacs version control interface is called VC.  Its commands work
>    with different version control systems---RCS, CVS, SCCS, Meta-CVS, GNU
>    Arch and Subversion.  The GNU project recommends and distributes
>    RCS, CVS, and GNU Arch.  We also have free software to replace
>    SCCS, known as CSSC; if you are using SCCS and don't want to make
>    the incompatible change to RCS or CVS, you can switch to CSSC.

Agreed,


        Stefan

Re: patch for documentation about version control

[Stefan Monnier]

>    "The GNU project recommends RCS, CVS, and GNU Arch which are
>     free software...",

> some readers could mistakenly infer that the other systems are *not*
> free software.  And because of that lead-in, the next sentence about a
> free replacement for SCCS only strengthens the misimpression.

I'd also suggest we don't recommend RCS any more.


        Stefan

Re: patch for documentation about version control

[David Kastrup]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>    "The GNU project recommends RCS, CVS, and GNU Arch which are
>>     free software...",
>
>> some readers could mistakenly infer that the other systems are *not*
>> free software.  And because of that lead-in, the next sentence about a
>> free replacement for SCCS only strengthens the misimpression.
>
> I'd also suggest we don't recommend RCS any more.

Why?  I don't think we have anything else to recommend for versioning
a single file, and without the need of a repository.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: patch for documentation about version control

[Thien-Thi Nguyen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

   I'd also suggest we don't recommend RCS any more.

although RCS is old (and somewhat quirky), it is still
useful.  i'm about to check in the following (changing
the names to have vc-rcs- prefix), which should extend
the lifetime of RCS ,v files if not the RCS executable
programs installed in ${bindir}, for a while yet.

i suppose support for ,v file munging does not conflict
directly w/ not recommending RCS any more, but it still
seems to me a slightly inconsistent message.

thi


_____________________________________________
;;; comma-v.el
;;;
;;; Rel:standalone-comma-v-el-2-0-0
;;;
;;; Copyright (C) 2004 Thien-Thi Nguyen
;;; This file is part of ttn's personal elisp library, released under GNU
;;; GPL with ABSOLUTELY NO WARRANTY.  See the file COPYING for details.
;;;
;;; Description: Read and write RCS-style masterfiles directly.

;;; Commentary:

;; Emacs is forever, but who knows whether or not ci(1) and co(1) will be
;; around in 20 years?  In any case, the true test for a data format is
;; how many programs can (easily) munge it.  Long live the ,v files!
;;
;; This library provides, at heart, two reciprocal functions:
;;   (comma-v-parse &optional buffer) => TREE
;;   (comma-v-unparse TREE &optional buffer)
;;
;; These have been tested only on simple ASCII files w/ "linear" revisions
;; (no branches, locks, access lists or other things).  There is some
;; quirkiness w/ RCS whitespace that probably will result in subtle errors.
;; Ahh, code-enhancement opportunities...
;;
;; Anyway, for the morbidly curious, here is the simple testing command:
;;
;; (defun comma-v-roundtrip (comma-v-file)
;;   (interactive "fRCS masterfile: ")
;;   (let* ((buf (find-file comma-v-file))
;;          (tree (comma-v-parse buf)))
;;     (switch-to-buffer "*comma-v-roundtrip*")
;;     (erase-buffer)
;;     (comma-v-unparse tree)
;;     (goto-char (point-min))
;;     (split-window-vertically)
;;     (switch-to-buffer-other-window buf)
;;     (goto-char (point-min))))
;;
;; You can then try `M-x compare-windows' and `C-u M-x compare-windows'.
;; Then for more fun, try it on a CVS-created ,v file.  This is known to
;; reveal miscompares for old ,v files where the year was stored as a two-
;; digit number (for example, 98 instead of 1998).  Obviously, overwriting
;; with a four-digit year is one way to prevent subsequent miscompares.
;;
;; Also provided are the functions:
;;   (comma-v-annotate-command file buffer &optional revision)
;;   (comma-v-annotate-current-time)
;;   (comma-v-annotate-time)
;;   (comma-v-annotate-extract-revision-at-line)
;;   (setup-anticipatory-vc-rcs-annotation)
;;
;; The last is a command that makes `C-x v g' work for RCS files
;; by hooking the other functions into the Emacs VC framework.
;; After some refinement they should be added to Emacs directly
;; along w/ -parse and -unparse, and comma-v.el declared obsolete.

;;; Code:

[snipped (to be added to vc-rcs.el in the next couple days) --ttn]

Re: patch for documentation about version control

[Andre Spiegel]

On Wed, 2004-11-10 at 04:00 -0500, Thien-Thi Nguyen wrote:

> although RCS is old (and somewhat quirky), it is still
> useful.  i'm about to check in the following (changing
> the names to have vc-rcs- prefix), which should extend
> the lifetime of RCS ,v files if not the RCS executable
> programs installed in ${bindir}, for a while yet.

Please don't add this.  RCS is perfectly alive and kicking, and to add
an alternative means of manipulating the master files (with subtle
incompatibilities admitted) is just plain unnecessary.

If you can use your parsing functions to make vc-annotate work under
RCS, that is a fine improvement, but please (a) let me see your patches
before you commit them, and (b) version control operations on RCS files
should always go via the actual RCS commands.

Re: patch for documentation about version control

[Thien-Thi Nguyen]

Andre Spiegel <spiegel@gnu.org> writes:

   Please don't add this.  RCS is perfectly alive and kicking, and to add
   an alternative means of manipulating the master files (with subtle
   incompatibilities admitted) is just plain unnecessary.

   If you can use your parsing functions to make vc-annotate work under
   RCS, that is a fine improvement, but please (a) let me see your patches
   before you commit them, and (b) version control operations on RCS files
   should always go via the actual RCS commands.

the patch is appended.  for the curious, there is also version 2.0.1 of
comma-v.el, from which the patch originated, in dir:

http://www.glug.org/people/ttn/software/ttn-pers-elisp/standalone/

as you can see, the patch does not actually change anything currently
defined in vc-rcs.el; it is purely additive.  btw, ORIG => 1.41.  if
there is a better way to get a file's per-line version info w/o parsing
the masterfile, please let me know in the next few days.  otherwise, i
will commit this so that vc-annotate is supported for RCS.

we can always ask the RCS maintainers to provide such info to Emacs in
the future (if we care), w/o being constrained by its present lack.

thi

____________________________________
diff -c vc-rcs.el.ORIG vc-rcs.el
*** vc-rcs.el.ORIG	Wed Nov 10 17:00:47 2004
--- vc-rcs.el	Wed Nov 10 17:35:19 2004
***************
*** 497,502 ****
--- 497,608 ----
                         (and newvers (concat "-r" newvers)))
                   (vc-switches 'RCS 'diff))))
  
+ (defun vc-rcs-annotate-command (file buffer &optional revision)
+   "Annotate FILE, inserting the results in BUFFER.
+ Optional arg REVISION is a revision to annotate from."
+   (let* ((tree (with-temp-buffer
+                  (insert-file-contents (vc-rcs-registered file))
+                  (vc-rcs-parse)))
+          (headers (cdr (assq 'headers tree)))
+          (revisions (cdr (assq 'revisions tree)))
+          (cur (cdr (assq 'head headers)))
+          (rbit (assoc cur revisions))
+          (meta (cdr rbit))
+          path pre delayed opp)
+     (unless revision
+       (setq revision cur))
+     (unless (assoc revision revisions)
+       (error "No such revision: %s" revision))
+     (set-buffer buffer)
+     ;; korg
+     (insert (cdr (assq 'text meta)))
+     (while (when (setq pre cur cur (cdr (assq 'next meta)))
+              (not (string= "" cur)))
+       (setq meta (cdr (assoc cur revisions))
+             opp nil
+             delayed nil)
+       (dolist (insn (cdr (assq :insn meta)))
+         (goto-line (pop insn))
+         (let ((p (point)))
+           (case (pop insn)
+             (k (push (let ((s (buffer-substring-no-properties
+                                p (progn (forward-line (car insn))
+                                         (point)))))
+                        `(,p ,(length s) I ,s))
+                      delayed))
+             (i (push (let ((s (car insn)))
+                        `(,p ,s K ,(length s)))
+                      delayed)))))
+       (dolist (p-act-ract (sort delayed (lambda (a b) (> (car a) (car b)))))
+         (let* ((p (pop p-act-ract))
+                (act (pop p-act-ract)))
+           (push (cons p p-act-ract) opp)
+           (goto-char p)
+           (funcall (if (numberp act)
+                        'delete-char
+                      'insert)
+                    act)))
+       (when (or path (string= revision pre))
+         (push `((:pre . ,pre)
+                 (:opp . ,opp)
+                 ,@meta)
+               path)))
+     (push `((:pre . ,pre)
+             (:opp . ((1 I ,(buffer-substring-no-properties
+                             (point-min) (point-max)))))
+             ,@meta)
+           path)
+     (erase-buffer)
+     ;; grok
+     (flet ((r/d/a (ls) (let ((r (cdr (assq :pre ls))))
+                          (let ((pre-ls (cdr (assoc r revisions))))
+                            (vector r
+                                    (cdr (assq 'date pre-ls))
+                                    (cdr (assq 'author pre-ls)))))))
+       (dolist (rbit path)
+         (dolist (insn (cdr (assq :opp rbit)))
+           (goto-char (pop insn))
+           (case (pop insn)
+             (I (insert (propertize (car insn)
+                                    :vc-rcs-r/d/a (r/d/a rbit)
+                                    'front-sticky '(:vc-rcs-r/d/a)
+                                    'rear-nonsticky t)))
+             (K (delete-char (car insn))))))))
+   ;; decorate
+   (goto-char (point-min))
+   (while (not (eobp))
+     (let ((r/d/a (get-text-property (point) :vc-rcs-r/d/a)))
+       (insert-and-inherit
+        ;; cvs envy (for now -- usurpers enjoy the dish best served cold)
+        (format "%-12s (%-8s %s): "      ; see `vc-rcs-annotate-time'
+                (aref r/d/a 0)
+                (aref r/d/a 2)
+                (format-time-string "%d-%b-%y" (aref r/d/a 1)))))
+     (forward-line 1)))
+ 
+ (defun vc-rcs-annotate-current-time ()
+   "Return the current time, based at midnight of the current day, and
+ encoded as fractional days."
+   (vc-annotate-convert-time
+    (apply 'encode-time 0 0 0 (nthcdr 3 (decode-time (current-time))))))
+ 
+ (defun vc-rcs-annotate-time ()
+   "Return the time of the next annotation (as fraction of days)
+ systime, or nil if there is none.  Also, reposition point."
+   (unless (eobp)
+     (forward-char                       ; see `vc-rcs-annotate-command'
+      (+ 12                              ; revision
+         2                               ; space + left paren
+         8                               ; author
+         1                               ; space
+         (+ 2 1 3 1 2)                   ; date
+         3))                             ; right paren + colon + space
+     (vc-annotate-convert-time
+      (aref (get-text-property (point) :vc-rcs-r/d/a) 1))))
+ 
+ (defun vc-rcs-annotate-extract-revision-at-line ()
+   (aref (get-text-property (point) :vc-rcs-r/d/a) 0))
+ 
  \f
  ;;;
  ;;; Snapshot system
***************
*** 784,789 ****
--- 890,1126 ----
  (defun vc-rcs-set-default-branch (file branch)
    (vc-do-command nil 0 "rcs" (vc-name file) (concat "-b" branch))
    (vc-file-setprop file 'vc-rcs-default-branch branch))
+ 
+ (defun vc-rcs-parse (&optional buffer)
+   ;; Parse current buffer, presumed to be in RCS-style masterfile format.
+   ;; Optional arg BUFFER specifies another buffer to parse.  Return an alist
+   ;; of two elements, w/ keys `headers' and `revisions' and values in turn
+   ;; sub-alists.  For `headers', the values unless otherwise specified are
+   ;; strings and the keys are:
+   ;;
+   ;;  desc     -- description
+   ;;  head     -- latest revision
+   ;;  access   -- ???
+   ;;  symbols  -- sub-alist of (SYMBOL . REVISION) elements
+   ;;  locks    -- if file is checked out, something like "ttn:1.7"
+   ;;  strict   -- ???
+   ;;  comment  -- typically something like "# " or "; "
+   ;;
+   ;; For `revisions', the car is REVISION (string), the cdr a sub-alist,
+   ;; with string values (unless otherwise specified) and keys:
+   ;;
+   ;;  date     -- a time value (like that returned by `encode-time'); as a
+   ;;              special case, a year value less than 100 is augmented by 1900
+   ;;  author   -- username
+   ;;  state    -- typically "Exp" or "Rel"
+   ;;  branches -- ???
+   ;;  next     -- next revision (which is actually prior in time!)
+   ;;  log      -- change log entry
+   ;;  text     -- for the head revision, this is the body of the file;
+   ;;              other revisions have `:insn' instead
+   ;;  :insn    -- for non-head revisions, a list of parsed instructions
+   ;;              in one of two forms, in both cases START meaning "first
+   ;;              go to line START":
+   ;;              - `(START k COUNT)' -- kill COUNT lines
+   ;;              - `(START i TEXT)'  -- insert TEXT (a string)
+   ;;
+   ;; The `:insn' key is a keyword to distinguish it as a vc-rcs.el value-added
+   ;; extra crispy not-found-in-stores bonus.
+   (setq buffer (get-buffer (or buffer (current-buffer))))
+   (set-buffer buffer)
+   (let (start context tok headers desc revs)
+     (setq start (point))
+     (goto-char (point-min))
+     (flet ((sw () (skip-chars-forward "[:space:]"))
+            (to-eol () (buffer-substring (point) (progn (forward-line 1)
+                                                        (1- (point)))))
+            (to-semi () (buffer-substring (point) (progn (search-forward ";")
+                                                         (1- (point)))))
+            (to-one@ () (buffer-substring
+                         (progn (search-forward "@") (point))
+                         (progn (while (and (search-forward "@")
+                                            (= ?@ (char-after))
+                                            (progn (forward-char 1) t)))
+                                (1- (point)))))
+            (tok+val (src name &optional proc)
+                     (if (not (eq name (setq tok (read buffer))))
+                         (error "Missing `%s' while parsing %s" name context)
+                       (sw)
+                       (cons tok (funcall (or proc 'identity)
+                                          (funcall src)))))
+            (k-semi (name &optional proc) (tok+val 'to-semi name proc))
+            (k-one@ (name &optional proc) (tok+val 'to-one@ name proc))
+            (@<-@@ (s) (with-temp-buffer
+                         (insert s)
+                         (while (search-backward "@@" (point-min) t)
+                           (delete-char 1))
+                         (buffer-string))))
+       ;; headers
+       (setq context 'headers)
+       (flet ((hpush (name &optional proc)
+                     (push (k-semi name proc) headers)))
+         (mapc 'hpush '(head access))
+         (hpush 'symbols
+                (lambda (x)
+                  (mapcar (lambda (together)
+                            (let ((two (split-string together ":")))
+                              (setcar two (intern (car two)))
+                              (setcdr two (cadr two))
+                              two))
+                          (split-string x))))
+         (mapc 'hpush '(locks strict)))
+       (push (tok+val                    ; ugh
+              (lambda ()
+                (unless (looking-at "@")
+                  (error "Malformed `comment' header"))
+                (forward-char 1)
+                (buffer-substring
+                 (point) (progn (search-forward "@;")
+                                (- (point) 2))))
+              'comment)
+             headers)
+       (setq headers (nreverse headers))
+       ;; rev headers
+       (sw) (setq context 'rev-headers)
+       (while (looking-at "[0-9]")
+         (push `(,(to-eol)
+                 ,(k-semi 'date
+                          (lambda (s)
+                            (apply 'encode-time
+                                   (let ((ls (mapcar 'string-to-number
+                                                     (split-string s "\\."))))
+                                     ;; hack the year -- verified to be the
+                                     ;; same algorithm used in RCS 5.7
+                                     (when (< (car ls) 100)
+                                       (setcar ls (+ 1900 (car ls))))
+                                     (reverse ls)))))
+                 ,@(mapcar 'k-semi '(author state branches next)))
+               revs)
+         (sw))
+       (setq revs (nreverse revs))
+       ;; desc
+       (sw) (setq context 'desc
+                  desc (k-one@ 'desc '@<-@@))
+       ;; rev bodies
+       (dolist (rev revs)
+         (sw)
+         (unless (string= (car rev) (to-eol))
+           (error "Missing rev body while parsing rev `%s'" (car rev)))
+         (push (k-one@ 'log  '@<-@@) (cdr rev))
+         (push (k-one@ 'text '@<-@@) (cdr rev))
+         (unless (string= (car rev) (cdr (assq 'head headers)))
+           (setcar (cadr rev) :insn)
+           (setcdr (cadr rev)
+                   (with-temp-buffer
+                     (insert (cdadr rev))
+                     (goto-char (point-min))
+                     (let (acc start act)
+                       (while (re-search-forward "^[ad]" (point-max) t)
+                         ;; d:a::k:i
+                         (setq start (read (current-buffer))
+                               act (read (current-buffer)))
+                         (push (if (string= "d" (match-string 0))
+                                   ;; `d' means "delete lines"
+                                   `(,start k ,act)
+                                 ;; `a' means "append after this line" but
+                                 ;; internally we normalize it so that START
+                                 ;; specifies the actual line for insert, thus
+                                 ;; requiring less hair in the realization algs
+                                 `(,(1+ start) i
+                                   ,(progn
+                                      (forward-char 1)
+                                      (buffer-substring-no-properties
+                                       (point)
+                                       (progn (forward-line act)
+                                              (point))))))
+                               acc))
+                       (nreverse acc))))))
+       (goto-char start)
+       ;; rv
+       `((headers ,desc ,@headers)
+         (revisions ,@revs)))))
+ 
+ ;;;; This is unused, included here for completeness.
+ ;;;; (IMHO, there is no harm in including it. --ttn)
+ ;;
+ ;;(defun vc-rcs-unparse (tree &optional buffer)
+ ;;  ;; Insert TREE into current buffer in RCS-style masterfile format.
+ ;;  ;; Optional second arg BUFFER specifies another buffer to insert into.
+ ;;  ;; You can use `vc-rcs-parse' to get TREE.
+ ;;  (setq buffer (get-buffer (or buffer (current-buffer))))
+ ;;  (let ((standard-output buffer)
+ ;;        (headers (cdr (assq 'headers tree)))
+ ;;        (revisions (cdr (assq 'revisions tree))))
+ ;;    (flet ((spew! (look name finish &optional proc)
+ ;;                  (princ name)
+ ;;                  (let ((v (funcall (or proc 'identity)
+ ;;                                    (funcall look name))))
+ ;;                    (unless (string= "" v)
+ ;;                      (unless proc
+ ;;                        (princ "\t"))
+ ;;                      (princ v)))
+ ;;                  (princ ";") (princ finish)))
+ ;;      (flet ((hspew (name finish &optional proc)
+ ;;                    (spew! (lambda (name) (cdr (assq name headers)))
+ ;;                           name finish proc)))
+ ;;        (hspew 'head "\n")
+ ;;        (hspew 'access "\n")
+ ;;        (hspew 'symbols "\n" (lambda (ls)
+ ;;                               (apply 'concat
+ ;;                                      (mapcar (lambda (x)
+ ;;                                                (format "\n\t%s:%s"
+ ;;                                                        (car x) (cdr x)))
+ ;;                                              ls))))
+ ;;        (hspew 'locks " ")
+ ;;        (hspew 'strict "\n")
+ ;;        (hspew 'comment "\n\n\n" (lambda (s) (format "\t@%s@" s))))
+ ;;      (dolist (rev revisions)
+ ;;        (princ (car rev))
+ ;;        (princ "\n")
+ ;;        (flet ((rlook (name) (cdr (assq name (cdr rev))))
+ ;;               (rspew (name finish &optional proc)
+ ;;                      (spew! 'rlook name finish proc)))
+ ;;          (rspew 'date "\t" (lambda (v)
+ ;;                              (format-time-string "\t%Y.%m.%d.%H.%M.%S" v)))
+ ;;          (rspew 'author "\t" (lambda (v) (concat " " v)))
+ ;;          (rspew 'state "\n" (lambda (v) (concat " " v)))
+ ;;          (rspew 'branches "\n")
+ ;;          (rspew 'next "\n\n"))))
+ ;;    (princ "\n")
+ ;;    (flet ((spew! (look name finish &optional proc)
+ ;;                  (princ name)
+ ;;                  (princ "\n@")
+ ;;                  (princ (with-temp-buffer
+ ;;                           (insert (funcall (or proc 'identity)
+ ;;                                            (funcall look name)))
+ ;;                           (while (search-backward "@" (point-min) t)
+ ;;                             (insert "@") (forward-char -1))
+ ;;                           (buffer-string)))
+ ;;                  (princ "@\n") (princ finish)))
+ ;;      (spew! (lambda (name) (cdr (assq name headers))) 'desc "")
+ ;;      (dolist (rev revisions)
+ ;;        (princ "\n\n") (princ (car rev)) (princ "\n")
+ ;;        (flet ((rlook (name) (cdr (assq name (cdr rev)))))
+ ;;          (spew! 'rlook 'log "")
+ ;;          (spew! (if (assq :insn (cdr rev))
+ ;;                     (let ((s (with-temp-buffer
+ ;;                                (dolist (cmd (rlook :insn))
+ ;;                                  (case (cadr cmd)
+ ;;                                    (k (insert (format "d%d %d\n"
+ ;;                                                       (car cmd)
+ ;;                                                       (caddr cmd))))
+ ;;                                    (i (insert (format "a%d "
+ ;;                                                       (1- (car cmd))))
+ ;;                                       (save-excursion
+ ;;                                         (insert (caddr cmd)))
+ ;;                                       (insert (format "%d\n"
+ ;;                                                       (count-lines
+ ;;                                                        (point) (point-max))))
+ ;;                                       (goto-char (point-max)))))
+ ;;                                (buffer-string))))
+ ;;                       `(lambda (x) ,s))
+ ;;                   'rlook)
+ ;;                 'text ""))))))
  
  (provide 'vc-rcs)

Re: patch for documentation about version control

[Andre Spiegel]

On Wed, 2004-11-10 at 11:43 -0500, Thien-Thi Nguyen wrote:

> as you can see, the patch does not actually change anything currently
> defined in vc-rcs.el; it is purely additive.  btw, ORIG => 1.41.  if
> there is a better way to get a file's per-line version info w/o parsing
> the masterfile, please let me know in the next few days.

It is fine to read information directly from the RCS master file, VC has
been doing that all along.  What about the efficiency of your parser,
though?  How long does it take to construct this full parse tree for a
large RCS master with many revisions?

Since we do need the line-by-line information, I guess there's not much
else we can do except to go for this full parse tree.

The code needs to be better commented.  It needs to explain in readable
English what you are doing at least in each major step.  "korg / grok /
decorate" is not enough.  This comment:

  ;; cvs envy (for now -- usurpers enjoy the dish best served cold)

is also not particularly helpful.

Finally, some of your variable names need to be improved.  A name like
"p-act-ract" or "r/d/a" is worse than a single-letter identifier because
the reader is left wondering what at all you are talking about.  Please
give meaningful names at least to these two variables/properties.

Please send me an updated version of your patch.  There is no need to do
this via emacs-devel, we can sort this out in personal mail.

Thanks for working on this; having vc-annotate work with RCS will be a
very worthwhile improvement.

Re: patch for documentation about version control

[Stefan]

> It is fine to read information directly from the RCS master file, VC has
> been doing that all along.  What about the efficiency of your parser,
> though?  How long does it take to construct this full parse tree for a
> large RCS master with many revisions?

Indeed, it would be better to do it directly as a patch to the RCS
sources...


        Stefan

Re: patch for documentation about version control

[Andre Spiegel]

On Thu, 2004-11-11 at 10:11 -0500, Stefan wrote:

> Indeed, it would be better to do it directly as a patch to the RCS
> sources...

We definitely need to run performance tests.  If we get acceptable
performance, both time and memory-wise, even for large RCS files, I'd
say let's do it.  I'll try out TTN's revised patch and we'll see.

Re: patch for documentation about version control

[Thien-Thi Nguyen]

thanks for reviewing the patch.
i will continue off-list, as you suggest.

thi

Re: patch for documentation about version control

[Thien-Thi Nguyen]

Andre Spiegel <spiegel@gnu.org> writes:

   What about the efficiency of your parser, though?  How long does it
   take to construct this full parse tree for a large RCS master with
   many revisions?

i haven't done any serious performance testing.  looking around locally,
the biggest file i could find was a ChangeLog of size 223492 bytes w/
252 revisions.  this is probably not representative since the typical
revision in such a file is to add some text at the top, very simple as
far as edits go...

anyway, on a 300MHz openbrick, w/ the modified vc-rcs.elc loaded,

(let ((start (current-time)))
  (call-interactively 'vc-annotate)
  (time-subtract (current-time) start))

=> (0 11)

other files i've tested to date have less revisions and are much faster,
no surprise.  probably a big win would be to avoid `with-temp-buffer'
when parsing the rev bodies, keeping all scanning in the current buffer
and consing a string only at the end.

thi

Re: patch for documentation about version control

[Thien-Thi Nguyen]

apparently, it is not only the parser that needs work:

  (defun ttn-test ()
    (interactive)
    (find-file "~/tmp/ChangeLog")
    (sit-for 0)
    (call-interactively 'vc-annotate))

elp results:

  Function Name            Call Count  Elapsed Time  Average Time
  =======================  ==========  ============  ============
  ttn-test                 1           13.740197     13.740197
  vc-rcs-annotate-command  1           12.956783     12.956783
  vc-rcs-parse             1           4.92826       4.92826

the vc-rcs-* funcs take 93% and 36% of the total time, respectively.
unfortunately, nothing comes to mind for `vc-rcs-annotate-command'
speedup.  suggestions welcome.

thi

Re: patch for documentation about version control

[Andre Spiegel]

On Thu, 2004-11-11 at 19:25 +0100, Thien-Thi Nguyen wrote:

> the vc-rcs-* funcs take 93% and 36% of the total time, respectively.
> unfortunately, nothing comes to mind for `vc-rcs-annotate-command'
> speedup.

So that means analyzing the tree takes longer than building it in the
first place, right?  I'm not sure what algorithm you use for that, since
I don't understand your code ;-)  Maybe there's a quadratic complexity
in there, which could be improved upon.  Did you check how CVS does it?

We'd have to test on a few more real-world files, and on a real-world
machine (forgive me, I mean >300MHz :-)  If it stays below a minute for
very large/complex change histories, I'd say we're still fine.

I have access to a few more complicated RCS masters, and will try your
code on those.

Re: patch for documentation about version control

[Thien-Thi Nguyen]

Andre Spiegel <spiegel@gnu.org> writes:

   So that means analyzing the tree takes longer than building it in the
   first place, right?  I'm not sure what algorithm you use for that, since
   I don't understand your code ;-)  Maybe there's a quadratic complexity
   in there, which could be improved upon.  Did you check how CVS does it?

no, i just applied the age-old reverse-engineering algorithm: futz around
until the output is the same (i confess peeking at RCS source to verify date
handling since i have no ,v files predating 1970)...  i will add explanatory
comments in the next patch.

   We'd have to test on a few more real-world files, and on a real-world
   machine (forgive me, I mean >300MHz :-)  If it stays below a minute for
   very large/complex change histories, I'd say we're still fine.

well earthling, thank you for your continuing hospitality... ;-)

thi

Re: patch for documentation about version control

[Andre Spiegel]

On Tue, 2004-11-09 at 16:34 -0500, Stefan Monnier wrote:

> I'd also suggest we don't recommend RCS any more.

I've rewritten the Introduction on Version Systems now, drawing from the
various suggestions.  It recommends CVS, GNU Arch, and RCS now, in that
order, and notes that RCS is useful for single files, while the others
are what you should consider for a full project.