mirror of https://github.com/texmacs/doc.git
Document new versioning facilities and changed conventions
This commit is contained in:
Joris van der Hoeven
parent
2380881feb
commit
a6e326eabe
|
|
@ -1,4 +1,4 @@
|
|||
<TeXmacs|1.0.7.4>
|
||||
<TeXmacs|1.0.7.15>
|
||||
|
||||
<style|tmdoc>
|
||||
|
||||
|
|
@ -10,28 +10,37 @@
|
|||
either accept, discard or further correct them. After enabling the
|
||||
versioning tool through <menu|Edit|Preferences|Utilities|Versioning tool>,
|
||||
a<nbsp>special menu <menu|Version> appears in the main menu bar, which
|
||||
makes this process automatic. Let us describe in more detail how this tool
|
||||
works.
|
||||
makes this process automatic. Below, we will describe in more detail how
|
||||
this tool works.
|
||||
|
||||
For the moment, automatic version control systems such as <name|Subversion>
|
||||
are not yet supported. In the future, we intend to include support for such
|
||||
systems and the operation of merging two different new versions.
|
||||
In addition, there exist many stand-alone programs for maintaining several
|
||||
versions of a same file, such as <hlink|<name|Subversion>|http://subversion.tigris.org/>,
|
||||
<hlink|<name|Git>|http://git-scm.com/>,
|
||||
<hlink|<name|Darcs>|http://darcs.net/>, <hlink|<name|GNU
|
||||
Arch>|http://www.gnu.org/software/gnu-arch/>, just to mention a few of
|
||||
them. <TeXmacs> currently provides a rudimentary support for
|
||||
<name|Subversion>, but interfaces for the other systems could easily be
|
||||
added.
|
||||
|
||||
<paragraph*|Comparing two versions>
|
||||
|
||||
Assume that we have two versions <verbatim|old.tm> and <verbatim|new.tm> of
|
||||
the same document. In order to see the changes, first load the newest
|
||||
version <verbatim|new.tm>, then click on <menu|Version|File|Compare> and
|
||||
select the oldest version <verbatim|old.tm>. The buffer will still be named
|
||||
<verbatim|new.tm>, and the changes between both versions will be indicated
|
||||
by special markup. If there are any changes, then the cursor will be
|
||||
positioned at the first difference.
|
||||
the same document. In order to see the changes, first load the newer
|
||||
version <verbatim|new.tm>, then click on <menu|Version|Compare|With older
|
||||
version> and select the older version <verbatim|old.tm>. The buffer will
|
||||
still be named <verbatim|new.tm>, and the changes between both versions
|
||||
will be indicated by special markup. If there are any changes, then the
|
||||
cursor will be positioned at the first difference. In a similar way, you
|
||||
may compare the current buffer to a<nbsp>newer version on disk using
|
||||
<menu|Version|Compare|With newer version>.
|
||||
|
||||
It is possible to go through all the differences between the old and new
|
||||
versions either from the items in the submenu <menu|Version|Move>, or using
|
||||
the keyboard shortcuts <shortcut|(version-previous-difference)> and <shortcut|(version-next-difference)>. One may also use the
|
||||
more general structured navigation shortcuts <shortcut|(traverse-first)>, <shortcut|(traverse-last)>,
|
||||
<shortcut|(traverse-previous)> and <shortcut|(traverse-next)>.
|
||||
the keyboard shortcuts <shortcut|(version-previous-difference)> and
|
||||
<shortcut|(version-next-difference)>. One may also use the more general
|
||||
structured navigation shortcuts <shortcut|(traverse-first)>,
|
||||
<shortcut|(traverse-last)>, <shortcut|(traverse-previous)> and
|
||||
<shortcut|(traverse-next)>.
|
||||
|
||||
<paragraph*|Visualization of the differences>
|
||||
|
||||
|
|
@ -41,14 +50,15 @@
|
|||
the new version in dark green.
|
||||
|
||||
The visualization style can be specified individually for each individual
|
||||
change, via <menu|Version|Show> or the keyboard shortcuts <shortcut|(version-show 'version-old)> (old
|
||||
version), <shortcut|(version-show 'version-new)> (new version) and <shortcut|(version-show 'version-both)> (both versions). One
|
||||
may also cycle through the different style using the structured variant key
|
||||
<shortcut|(variant-circulate (focus-tree) #t)>. If you selected some text, then the above actions will apply
|
||||
to the whole selection. The visualization style may also be specified
|
||||
globally, using <menu|Version|File|Show old version>,
|
||||
<menu|Version|File|Show new version> and <menu|Version|File|Show both
|
||||
versions>.
|
||||
change, via <menu|Version|Show> or the keyboard shortcuts
|
||||
<shortcut|(version-show 'version-old)> (old version),
|
||||
<shortcut|(version-show 'version-new)> (new version) and
|
||||
<shortcut|(version-show 'version-both)> (both versions). One may also cycle
|
||||
through the different style using the structured variant key
|
||||
<shortcut|(variant-circulate (focus-tree) #t)>. If you selected some text,
|
||||
then the above actions will apply to the whole selection. In particular, by
|
||||
selecting the entire file, you can visualize the older or the newer
|
||||
version, or both versions.
|
||||
|
||||
<paragraph*|Retaining a specific version>
|
||||
|
||||
|
|
@ -56,22 +66,24 @@
|
|||
and progressively retain either one or the other version for each
|
||||
individual difference. Assuming that the cursor is inside a given
|
||||
difference, this can be done from entries in the submenu
|
||||
<menu|Version|Retain>. Alternatively, one may use the shortcuts <shortcut|(version-retain 0)>,
|
||||
<shortcut|(version-retain 1)> and <shortcut|(version-retain 'current)> to retain the old, new and currently displayed
|
||||
version, respectively. If both versions are displayed, then <shortcut|(version-retain 'current)>
|
||||
retains the new version. After retaining one of the versions, we
|
||||
automatically jump to the next difference, which can then be processed. If
|
||||
you selected some text, then any of the above action will retain the
|
||||
appropriate version for each of the differences in the selection.
|
||||
<menu|Version|Retain>. Alternatively, one may use the shortcuts
|
||||
<shortcut|(version-retain 0)>, <shortcut|(version-retain 1)> and
|
||||
<shortcut|(version-retain 'current)> to retain the old, new and currently
|
||||
displayed version, respectively. If both versions are displayed, then
|
||||
<shortcut|(version-retain 'current)> retains the new version. After
|
||||
retaining one of the versions, we automatically jump to the next
|
||||
difference, which can then be processed.
|
||||
|
||||
It is also possible to globally select the old, new or current version
|
||||
using <menu|Version|File|Retain old version>, <menu|Version|File|Retain new
|
||||
version>, <abbr|resp.> <menu|Version|File|Retain current version>. A
|
||||
convenient alternative way to process all differences is to use <shortcut|(version-previous-difference)>
|
||||
and <shortcut|(version-next-difference)> to go through the differences, use <shortcut|(version-show 'version-old)> and
|
||||
<shortcut|(version-show 'version-new)> to select the preferred version, and then click on
|
||||
<menu|Version|File|Retain current version> as soon as all differences have
|
||||
been processed.
|
||||
If you selected some text, then any of the above action will retain the
|
||||
appropriate version for each of the differences in the selection. This
|
||||
applies in particular to the case when you select the entire document. A
|
||||
convenient alternative way to process all differences is to use
|
||||
<shortcut|(version-previous-difference)> and
|
||||
<shortcut|(version-next-difference)> to go through the differences, use
|
||||
<shortcut|(version-show 'version-old)> and <shortcut|(version-show
|
||||
'version-new)> to select the preferred version. As soon as all differences
|
||||
have been processed, you select the entire document and click on
|
||||
<menu|Version|Retain|Current version>.
|
||||
|
||||
<paragraph*|Grain control and reactualizing the differences>
|
||||
|
||||
|
|
@ -81,22 +93,55 @@
|
|||
differences on a paragraph-based level, using <menu|Block>. In that case,
|
||||
the entire paragraphs in which a change occurs will be highlighted. The
|
||||
roughest grain <menu|Rough> will highlight the entire text, if a change
|
||||
occurs within it.
|
||||
occurs somewhere inside.
|
||||
|
||||
The grain is used when comparing two documents using
|
||||
<menu|Version|File|Compare>, but it is also possible to recompare the
|
||||
differences in a selected portion of text using <menu|Version|Reactualize>.
|
||||
The latter possibility is especially useful after a change the grain.
|
||||
<menu|Version|File|Compare>, but it is also possible to change the grain
|
||||
for a selected portion of text: simply select the text and choose the new
|
||||
grain in the submenu <menu|Version|Grain>. This can in particular be
|
||||
applied on the entire buffer. Similarly, if you change the grain inside a
|
||||
difference, then the difference will be recomputed using the new grain.
|
||||
|
||||
Similarly, the cursor is inside a difference, then you may recompare the
|
||||
two versions <menu|Version|Reactualize>. This may be useful, if you made
|
||||
some changes to one of the versions. For instance, assume that the old
|
||||
Notice that you may also ``change'' the grain to the current grain. This
|
||||
has the effect of reactualizing the differences of a selected portion or of
|
||||
the current difference at the cursor position. This may be useful, if you
|
||||
made some changes to one of the versions. For instance, assume that the old
|
||||
version contained a theorem and that we changed it into a lemma in the new
|
||||
version and also modified part of its inside text. When visualizing the
|
||||
changes, the whole theorem will be highlighted, since there is no
|
||||
appropriate markup to indicate that we just changed from a<nbsp>theorem to
|
||||
a lemma. Nevertheless, if we want to compare the inside texts, we may turn
|
||||
the old theorem into a lemma and then click on <menu|Version|Reactualize>.
|
||||
the old theorem into a lemma and then reactualize.
|
||||
|
||||
<paragraph*|Using external programs for version control such as
|
||||
<name|Subversion>>
|
||||
|
||||
If the file you are editing belongs to a directory which is under version
|
||||
control (only <name|Subversion> is currently supported, although other
|
||||
systems might follow), then the first part of the <menu|Version> menu will
|
||||
contain some clickable entries.
|
||||
|
||||
First of all, if the current buffer is under version control, then you may
|
||||
take a look at its history using <menu|Version|History>. The history
|
||||
contains a list of hyperlinks to older revisions, together with short
|
||||
information about who changed what and when. Older revisions cannot be
|
||||
saved, but you may compare them to the current user version (on disk or
|
||||
being edited) using <menu|Version|Compare|With current user version>.
|
||||
|
||||
After making some changes to a file under version control, the version
|
||||
inside the editor or on disk no longer corresponds to the version in the
|
||||
repository. Using<nbsp><menu|Version|Commit>, the current user's version
|
||||
can be committed to the repository. When doing so, you will be prompted for
|
||||
a small explanatory message about the changes that you have made. A file
|
||||
which is not yet under version control can be added to the version control
|
||||
system using <menu|Version|Register>. Registering a file does <em|not>
|
||||
commit it to the repository; you still have to use <menu|Version|Commit> in
|
||||
order to do so.
|
||||
|
||||
If, while you were editing, changes to the file were made in the
|
||||
repository, then you may merge the result with your current version using
|
||||
<menu|Version|Update>. At the moment, no conflict resolution has been
|
||||
implemented yet, although this is planned for the future.
|
||||
|
||||
<tmdoc-copyright|2010|Joris van der Hoeven>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue