log-view documentation

log-view documentation

[Aaron S. Hawley]

log-view is pretty cool. it should be documented.

A proposal is below.  It is copied (via Kill and Yank) from the commands
documented for the "annotate buffer", found in the "Old Versions" section
of the manual.

--- files.texi	18 Nov 2005 13:54:05 -0500	1.122
+++ files.texi	22 Nov 2005 12:32:38 -0500
@@ -1790,8 +1790,50 @@
 @findex vc-print-log
   To view the detailed version control status and history of a file,
 type @kbd{C-x v l} (@code{vc-print-log}).  It displays the history of
-changes to the current file, including the text of the log entries.  The
-output appears in a separate window.
+changes to the current file, including the text of the log entries.  The
+output appears in a separate window.  The point is centered at the
+revision of the file that was currently visited.
+
+From the change log buffer, the following keys can be used to move
+between the logs of files and revisions, to view past revisions, and
+to view diffs:
+
+@itemize @bullet
+
+@item
+Pressing @kbd{p} moves to the previous revision of the file.  It also
+takes a numeric prefix argument, so for example @kbd{C-u 10 p} would
+take you back 10 revisions.
+
+@item
+Pressing @kbd{n} moves to the next revision of the file.  It also
+takes a numeric prefix argument, so for example @kbd{C-u 10 n} would
+take you forward 10 revisions.
+
+@item
+Pressing @kbd{f} visits the revision at the current line, like typing
+@kbd{C-x v ~} and specifying the revision.
+
+@item
+Pressing @kbd{d} shows the diff of the revision at line with its
+previous revision.  This is useful to see what actually changed when
+the revision denoted on the current line was committed.
+
+@item
+Pressing @kbd{P} moves to the log of the previous file.  when there
+are multiple files in the log buffer (@pxref{VC Dired Mode}).
+Otherwise, it moves to the beginning of the log.  It also takes a
+numeric prefix argument, so for example @kbd{C-u 10 P} would take you
+back 10 files.
+
+@item
+Pressing @kbd{N} moves to the log of the next file if there are logs
+for multiple files in the log buffer (@pxref{VC Dired Mode}).
+Otherwise, it moves to the end of the log.  It also takes a numeric
+prefix argument, so for example @kbd{C-u 10 N} would take you forward
+10 files.
+
+@end itemize

 @node VC Undo
 @subsubsection Undoing Version Control Actions

Re: log-view documentation

[Richard M. Stallman]

Thanks for writing text to document log-view mode.

    +@itemize @bullet
    +
    +@item
    +Pressing @kbd{p} moves to the previous revision of the file.  It also

Our style is to use @table @kbd for this.
Please look at other such lists in the manual
to see the proper style, especially for index entries
and for giving the names of the commands.

Aside from that, this is large enough that we will need
some kind of legal papers.  Would you like to sign papers
for Emacs changes?

Re: log-view documentation

[Nick Roberts]

Richard M. Stallman writes:
 > Thanks for writing text to document log-view mode.
 > 
 >     +@itemize @bullet
 >     +
 >     +@item
 >     +Pressing @kbd{p} moves to the previous revision of the file.  It also
 > 
 > Our style is to use @table @kbd for this.
 >
 > Please look at other such lists in the manual
 > to see the proper style, especially for index entries
 > and for giving the names of the commands.

I would guess he has looked at other lists in the manual.  The above style is
currently used for vc-annotate (Node: Old Versions).

Nick

Re: log-view documentation

[Richard M. Stallman]

    I would guess he has looked at other lists in the manual.  The above style is
    currently used for vc-annotate (Node: Old Versions).

If vc-annotate is inconsistent with the rest of the manual,
I think that needs to be fixed.  We should clean up inconcistency
that serves no particular purpose, not extend it.

Here I have put that table into our usual format.
I have also tried clearing up certain descriptions
whose meaning I was not certain of.  I am partly guessing
(since I don't use this feature), so if any of this is wrong,
could someone tell me?


@table @kbd
@item P
Annotate the previous revision, that is to say, the revision before
the one currently annotated.  A numeric prefix argument is a repeat
count, so @kbd{C-u 10 P} would take you back 10 revisions.

@item N
Annotate the next revision---the one after the revision currently
annotated.  A numeric prefix argument is a repeat count.

@item J
Annotate the revision indicated by the current line.

@item A
Annotate the revision before the one indicated by the current line.
This is useful to see the state the file was in before the change on
the current line was made.

@item D
Display the diff between the revision indicated the current line line
and the revision before it.  This is useful to see what actually
changed when the revision indicated by the current line was committed.

@item L
Show the log of the current line's revision.  This is useful to see
the author's description of the changes in the revision on the current
line.

@item W
Annotate the workfile version--the one you are editing.  If you used
@kbd{P} and @kbd{N} to browse to other revisions, use this key to
return to the latest version.
@end table

Re: log-view documentation

[Nick Roberts]

 > Here I have put that table into our usual format.
 > I have also tried clearing up certain descriptions
 > whose meaning I was not certain of.  I am partly guessing
 > (since I don't use this feature), so if any of this is wrong,
 > could someone tell me?

I've not used it much, but it seems OK to me.

 ...
 > @item J
 > Annotate the revision indicated by the current line.
 > 
 > @item A
 > Annotate the revision before the one indicated by the current line.
 > This is useful to see the state the file was in before the change on
 > the current line was made.

I think you might look at the revision indicated by the current line before
the previous one (which can currently be done with `J' then `P'.

How about using A for annotating the revision indicated by the current line
(its more mnemonic) and C-u A for the revision before the one indicated by the
current line?  Tthis feature is not in Emacs 21, so now would be a good time to
change it.

Nick

Re: log-view documentation

[Richard M. Stallman]

    I think you might look at the revision indicated by the current line before
    the previous one (which can currently be done with `J' then `P'.

I don't understand the suggestion.  Could you possibly give me a patch
to my text which would show your suggestion?

    How about using A for annotating the revision indicated by the current line
    (its more mnemonic) and C-u A for the revision before the one indicated by the
    current line?

Since J annotates the revision indicated by the current line, wouldn't
it be redundant for A to do that too?  And wouldn't C-u A be less
convenient than A?

But since I don't use this feature, I don't have a strong opinion.

Re: log-view documentation

[Nick Roberts]

 > Since J annotates the revision indicated by the current line, wouldn't
 > it be redundant for A to do that too?  And wouldn't C-u A be less
 > convenient than A?
 > 
 > But since I don't use this feature, I don't have a strong opinion.

I have been trying it, but find it hard to use.  It might be helpful to have
Info like navigation (albeit slow) and retain buffers with earlier versions.
But I don't really use it either, so let's leave it as it is.

Nick

Re: log-view documentation

[Aaron S. Hawley]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1751 bytes --]

On Wed, 23 Nov 2005, Richard M. Stallman wrote:

> Our style is to use @table @kbd for this.
> Please look at other such lists in the manual
> to see the proper style, especially for index entries
> and for giving the names of the commands.

That makes sense.  I was confused by the commands marked up as a list in
the "Old Versions" node -- no longer!

I've modified the patch to use the Texinfo table style.  I adopted (read:
copied)  and incorporated respectively the wording changes you've proposed
for documenting `vc-annotate'.  I also added some more cross references.
The patch is attached, but here's the table.

 @table @kbd

 @item p
 Move to the previous revision of the file.  A numeric prefix argument
 is a repeat count, so @kbd{C-u 10 p} would move backward 10 revisions.

 @item n
 Move to the next revision of the file.  A numeric prefix argument
 is a repeat count.

 @item f
 Visit the revision indicated at the current line, like typing @kbd{C-x
 v ~} and specifying the revision (@pxref{Old Versions}).

 @item d
 Display the diff (@pxref{Comparing Files}) between the revision
 indicated at the current line and the revision before it.  This is
 useful to see what actually changed when the revision indicated on the
 current line was committed.

 @item P
 Move to the log of the previous file when there are multiple files in
 the log buffer (@pxref{VC Dired Mode}).  Otherwise, it moves to the
 beginning of the log.  It also takes a numeric prefix argument as a
 repeat count, so @kbd{C-u 10 P} would move backward 10 files.

 @item N
 Move to the log of the next file when there are logs for multiple
 files in the log buffer (@pxref{VC Dired Mode}).  It also takes a
 numeric prefix argument as a repeat count.

 @end table

[-- Attachment #2: log-view patch --]
[-- Type: TEXT/PLAIN, Size: 1894 bytes --]

--- files.texi	18 Nov 2005 13:54:05 -0500	1.122
+++ files.texi	25 Nov 2005 19:22:12 -0500	
@@ -1791,7 +1791,45 @@
   To view the detailed version control status and history of a file,
 type @kbd{C-x v l} (@code{vc-print-log}).  It displays the history of
 changes to the current file, including the text of the log entries.  The
-output appears in a separate window.
+output appears in a separate window.  The point is centered at the
+revision of the file that was currently visited.
+
+From the change log buffer, the following keys can be used to move
+between the logs of files and revisions, to view past revisions, and
+to view diffs:
+
+@table @kbd
+
+@item p
+Move to the previous revision of the file.  A numeric prefix argument
+is a repeat count, so @kbd{C-u 10 p} would move backward 10 revisions.
+
+@item n
+Move to the next revision of the file.  A numeric prefix argument
+is a repeat count.
+
+@item f
+Visit the revision indicated at the current line, like typing @kbd{C-x
+v ~} and specifying the revision (@pxref{Old Versions}).
+
+@item d
+Display the diff (@pxref{Comparing Files}) between the revision
+indicated at the current line and the revision before it.  This is
+useful to see what actually changed when the revision indicated on the
+current line was committed.
+
+@item P
+Move to the log of the previous file when there are multiple files in
+the log buffer (@pxref{VC Dired Mode}).  Otherwise, it moves to the
+beginning of the log.  It also takes a numeric prefix argument as a
+repeat count, so @kbd{C-u 10 P} would move backward 10 files.
+
+@item N
+Move to the log of the next file when there are logs for multiple
+files in the log buffer (@pxref{VC Dired Mode}).  It also takes a
+numeric prefix argument as a repeat count.
+
+@end table
 
 @node VC Undo
 @subsubsection Undoing Version Control Actions

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

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

Re: log-view documentation

[Aaron S. Hawley]

On Wed, 23 Nov 2005, Richard M. Stallman wrote:

> Here I have put that table into our usual format.
> I have also tried clearing up certain descriptions
> whose meaning I was not certain of.  I am partly guessing
> (since I don't use this feature), so if any of this is wrong,
> could someone tell me?

I've never used the feature, but noticed this in the change:

> @item D
> Display the diff between the revision indicated the current line line
> and the revision before it.

After "indicated", add "at".
Remove one of the duplicated words, "line".

/a

Re: log-view documentation

[Richard M. Stallman]

When your papers come, I will ask you to send the current version
for installation.

re: log-view documentation

[Aaron S. Hawley]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1898 bytes --]

My copyright papers came back from the FSF copyright clerk.

Here's my current version of documentation for the log-view commands for
inclusion in the Emacs manual.  A "context" patch is attached.

Thanks,
/a

----

  To view the detailed version control status and history of a file,
type @kbd{C-x v l} (@code{vc-print-log}).  It displays the history of
changes to the current file, including the text of the log entries.  The
output appears in a separate window.  The point is centered at the
revision of the file that is currently being visited.

>From the change log buffer, the following keys are used to move
between the logs of files and revisions, to view past revisions, and
to view diffs:

@table @kbd

@item p
Move to the previous revision of the file.  A numeric prefix argument
is a repeat count, so @kbd{C-u 10 p} would move backward 10 revisions.

@item n
Move to the next revision of the file.  A numeric prefix argument
is a repeat count.

@item f
Visit the revision indicated at the current line, like typing @kbd{C-x
v ~} and specifying the revision (@pxref{Old Versions}).

@item d
Display the diff (@pxref{Comparing Files}) between the revision
indicated at the current line and the revision before it.  This is
useful to see what actually changed when the revision indicated on the
current line was committed.

@item P
Move to the log of the previous file when the logs of multiple files
are in the log buffer (@pxref{VC Dired Mode}).  Otherwise, the point
just moves to the beginning of the log.  A numeric prefix argument is
a repeat count, so @kbd{C-u 10 P} would move backward 10 files.

@item N
Move to the log of the next file when the logs of multiple files are
in the log buffer (@pxref{VC Dired Mode}).  It also takes a numeric
prefix argument as a repeat count.

@end table

----
previous thread:
<http://lists.gnu.org/archive/html/emacs-devel/2005-11/msg01225.html>

[-- Attachment #2: Type: TEXT/PLAIN, Size: 2268 bytes --]

*** files.texi	18 Nov 2005 13:54:05 -0500	1.122
--- files.texi	14 Dec 2005 00:54:07 -0500	
***************
*** 1791,1797 ****
    To view the detailed version control status and history of a file,
  type @kbd{C-x v l} (@code{vc-print-log}).  It displays the history of
  changes to the current file, including the text of the log entries.  The
! output appears in a separate window.
  
  @node VC Undo
  @subsubsection Undoing Version Control Actions
--- 1791,1835 ----
    To view the detailed version control status and history of a file,
  type @kbd{C-x v l} (@code{vc-print-log}).  It displays the history of
  changes to the current file, including the text of the log entries.  The
! output appears in a separate window.  The point is centered at the
! revision of the file that is currently being visited.
! 
! From the change log buffer, the following keys are used to move
! between the logs of files and revisions, to view past revisions, and
! to view diffs:
! 
! @table @kbd
! 
! @item p
! Move to the previous revision of the file.  A numeric prefix argument
! is a repeat count, so @kbd{C-u 10 p} would move backward 10 revisions.
! 
! @item n
! Move to the next revision of the file.  A numeric prefix argument
! is a repeat count.
! 
! @item f
! Visit the revision indicated at the current line, like typing @kbd{C-x
! v ~} and specifying the revision (@pxref{Old Versions}).
! 
! @item d
! Display the diff (@pxref{Comparing Files}) between the revision
! indicated at the current line and the revision before it.  This is
! useful to see what actually changed when the revision indicated on the
! current line was committed.
! 
! @item P
! Move to the log of the previous file when the logs of multiple files
! are in the log buffer (@pxref{VC Dired Mode}).  Otherwise, the point
! just moves to the beginning of the log.  A numeric prefix argument is
! a repeat count, so @kbd{C-u 10 P} would move backward 10 files.
! 
! @item N
! Move to the log of the next file when the logs of multiple files are
! in the log buffer (@pxref{VC Dired Mode}).  It also takes a numeric
! prefix argument as a repeat count.
! 
! @end table
  
  @node VC Undo
  @subsubsection Undoing Version Control Actions

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

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

Re: log-view documentation

[Juri Linkov]

> Here's my current version of documentation for the log-view commands for
> inclusion in the Emacs manual.  A "context" patch is attached.
>
> [...]
>
> @item p
> Move to the previous revision of the file.  A numeric prefix argument
> is a repeat count, so @kbd{C-u 10 p} would move backward 10 revisions.
>
> @item n
> Move to the next revision of the file.  A numeric prefix argument
> is a repeat count.
>
> @item d
> Display the diff (@pxref{Comparing Files}) between the revision
> indicated at the current line and the revision before it.  This is
> useful to see what actually changed when the revision indicated on the
> current line was committed.

You could mention also how it works if there is the active mark in
the log-view buffer.  Please see the final version of the docstring for
log-view-diff in

http://lists.gnu.org/archive/html/emacs-pretest-bug/2005-12/msg00066.html

Also in the same thread Richard pointed out that actually `n' moves
to the the previous revision, and `p' moves to the next revision,
and not vice versa.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: log-view documentation

[Aaron S. Hawley]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1218 bytes --]

On Wed, 14 Dec 2005, Juri Linkov wrote:

> You could mention also how it works if there is the active mark in
> the log-view buffer.

> Also in the same thread Richard pointed out that actually `n' moves
> to the the previous revision, and `p' moves to the next revision,
> and not vice versa.

Hah, I never thought of it like that.  Good catch.

Thanks for bring both of these to my attention.

I've attached an updated patch.

Here's how it changed from the previous patch:

@item p
Move to the @emph{next} revision of the file.  Revision entries in the
log buffer are listed in descending order, therefore revision motion
is the inverse of point motion.  A numeric prefix argument is a repeat
count, so @kbd{C-u 10 p} would move 10 revisions.

@item n
Move to the @emph{previous} revision of the file.  A numeric prefix argument
is a repeat count.

[...]

@item d
Display the diff (@pxref{Comparing Files}) between the revision
indicated at the current line and the revision before it.  This is
useful to see what actually changed when the revision indicated on the
current line was committed.  When the mark is active (@pxref{Mark}),
display the diff between the revisions found at the start and end of
the region.

[-- Attachment #2: Type: TEXT/PLAIN, Size: 2724 bytes --]

Index: files.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/files.texi,v
retrieving revision 1.123
diff -u -r1.123 files.texi
*** files.texi	12 Dec 2005 00:55:25 -0000	1.123
--- files.texi	14 Dec 2005 17:45:24 -0000
***************
*** 1788,1794 ****
    To view the detailed version control status and history of a file,
  type @kbd{C-x v l} (@code{vc-print-log}).  It displays the history of
  changes to the current file, including the text of the log entries.  The
! output appears in a separate window.
  
  @node VC Undo
  @subsubsection Undoing Version Control Actions
--- 1788,1836 ----
    To view the detailed version control status and history of a file,
  type @kbd{C-x v l} (@code{vc-print-log}).  It displays the history of
  changes to the current file, including the text of the log entries.  The
! output appears in a separate window.  The point is centered at the
! revision of the file that is currently being visited.
! 
! From the change log buffer, the following keys are used to move
! between the logs of files and revisions, to view past revisions, and
! to view diffs:
! 
! @table @kbd
! 
! @item p
! Move to the @emph{next} revision of the file.  Revision entries in the
! log buffer are listed in descending order, therefore revision motion
! is the inverse of point motion.  A numeric prefix argument is a repeat
! count, so @kbd{C-u 10 p} would move 10 revisions.
! 
! @item n
! Move to the @emph{previous} revision of the file.  A numeric prefix argument
! is a repeat count.
! 
! @item f
! Visit the revision indicated at the current line, like typing @kbd{C-x
! v ~} and specifying the revision (@pxref{Old Versions}).
! 
! @item d
! Display the diff (@pxref{Comparing Files}) between the revision
! indicated at the current line and the revision before it.  This is
! useful to see what actually changed when the revision indicated on the
! current line was committed.  When the mark is active (@pxref{Mark}),
! display the diff between the revisions found at the start and end of
! the region.
! 
! @item P
! Move to the log of the previous file when the logs of multiple files
! are in the log buffer (@pxref{VC Dired Mode}).  Otherwise, the point
! just moves to the beginning of the log.  A numeric prefix argument is
! a repeat count, so @kbd{C-u 10 P} would move backward 10 files.
! 
! @item N
! Move to the log of the next file when the logs of multiple files are
! in the log buffer (@pxref{VC Dired Mode}).  It also takes a numeric
! prefix argument as a repeat count.
! 
! @end table
  
  @node VC Undo
  @subsubsection Undoing Version Control Actions

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

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