GNOME.org
 

[meld] Introduce newly-written Mallard-based help

commit 1cbd1126e03b6daa5b728b90e929b3ce3188ba02
Author: Kai Willadsen <kai willadsen gmail com>
Date:   Tue Jun 5 06:33:24 2012 +1000

    Introduce newly-written Mallard-based help

 help/C/file-changes.page          |   61 +++++++++++++++++
 help/C/file-mode.page             |   53 +++++++++++++++
 help/C/filtering-files.page       |   21 ++++++
 help/C/filtering-text.page        |  121 ++++++++++++++++++++++++++++++++++
 help/C/index.page                 |   33 ++++++++++
 help/C/introduction.page          |   23 +++++++
 help/C/keyboard-shortcuts.page    |  129 +++++++++++++++++++++++++++++++++++++
 help/C/legal.xml                  |    9 +++
 help/C/missing-functionality.page |   18 +++++
 help/C/resolvingconflicts.page    |   29 ++++++++
 help/C/startingmeld.page          |   38 +++++++++++
 help/C/vc-supported.page          |   34 ++++++++++
 12 files changed, 569 insertions(+), 0 deletions(-)
---
diff --git a/help/C/file-changes.page b/help/C/file-changes.page
new file mode 100644
index 0000000..d8587ef
--- /dev/null
+++ b/help/C/file-changes.page
@@ -0,0 +1,61 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="file-changes">
+<info>
+  <title type="sort">2</title>
+  <link type="guide" xref="index#file-mode"/>
+</info>
+
+<title>Dealing with changes</title>
+
+<p>
+<app>Meld</app> deals with differences between files as a list of <em>change
+blocks</em> or more simply <em>changes</em>. Each change is a group of lines
+which correspond between files. Since these changes are what you're usually
+interested in, <app>Meld</app> gives you specific tools to navigate between
+these changes and to edit them. You can find these tools in the
+<gui style="menu">Changes</gui> menu.
+</p>
+
+
+
+<section id="change-navigation">
+<title>Navigating between changes</title>
+
+<p>
+You can navigate between changes with the
+<guiseq><gui style="menu">Changes</gui><gui style="menuitem">Previous change</gui></guiseq>
+and
+<guiseq><gui style="menu">Changes</gui><gui style="menuitem">Next change</gui></guiseq>
+menu items. You can also use your mouse's scroll wheel to move between chunks,
+by scrolling on the central change bar.
+</p>
+
+</section>
+
+
+
+<section id="change-actions">
+<title>Changing changes</title>
+
+<p>
+In addition to directly editing text files, <app>Meld</app> gives you tools to move, copy or delete individual differences between files. The bar between two files not only shows you what parts of the two files correspond, but also lets you selectively merge or delete differing chunks by clicking the arrow or cross icons next to the start of each chunk.
+</p>
+
+<p>
+The default action is <em>replace</em>. This action replaces the contents of the corresponding chunk with the current chunk.
+</p>
+<comment>
+  <cite date="2010-02-25" href="mailto:kai willadsen gmail com">Kai</cite>
+  <p>It would be nice to have small video clips inlined that demonstrated exactly what each action did.</p>
+</comment>
+<p>
+Hold down the <key>Shift</key> key to change the current action to <em>delete</em>. This action deletes the current chunk.
+</p>
+<p>
+Hold down the <key>Ctrl</key> key to change the current action to <em>insert</em>. This action inserts the current chunk above or below (as selected) the corresponding chunk.
+</p>
+
+</section>
+
+</page>
diff --git a/help/C/file-mode.page b/help/C/file-mode.page
new file mode 100644
index 0000000..d677248
--- /dev/null
+++ b/help/C/file-mode.page
@@ -0,0 +1,53 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="file-mode">
+<info>
+  <title type="sort">1</title>
+  <link type="guide" xref="index#file-mode"/>
+  <link type="seealso" xref="file-changes"/>
+</info>
+
+<title>Getting started comparing files</title>
+
+<p>
+<app>Meld</app> lets you compare two or three text files side-by-side. You can
+start a new file comparison by selecting the
+<guiseq><gui style="menu">File</gui><gui style="menuitem">New...</gui></guiseq>
+menu item.
+</p>
+
+<p>
+Once you've selected your files, <app>Meld</app> will show them side-by-side.
+Differences between the files will be highlighted to make individual changes
+easier to see. Editing the files will cause the comparison to update
+on-the-fly. For details on navigating between individual changes, and on
+how to use change-based editing, see <link xref="file-changes"/>.
+</p>
+
+<section>
+<title><app>Meld</app>'s file comparisons</title>
+
+<p>
+There are several different parts to a file comparison. The most important
+parts are the editors where your files appear. In addition to these editors,
+the areas around and between your files give you a visual overview and actions
+to help you handle changes between the files.
+</p>
+<p>
+On the left and right-hand sides of the window, there are two small vertical
+bars showing various coloured blocks. These bars are designed to give you an
+overview of all of the differences between your two files. Each coloured block
+represents a section that is inserted, deleted, changed or in conflict between
+your files, depending on the block's colour used.
+</p>
+<p>
+In between each pair of files is a segment that shows how the changed sections
+between your files correspond to each other. You can click on the arrows in a
+segment to replace sections in one file with sections from the other. You can
+also delete, copy or merge changes. For details on what you can do with
+individual change segments, see <link xref="file-changes#change-actions"/>.
+</p>
+
+</section>
+
+</page>
diff --git a/help/C/filtering-files.page b/help/C/filtering-files.page
new file mode 100644
index 0000000..445e8b4
--- /dev/null
+++ b/help/C/filtering-files.page
@@ -0,0 +1,21 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="file-filters">
+<info>
+  <title type="sort">2</title>
+  <link type="guide" xref="index#folder-mode"/>
+</info>
+<title>Filtering out files</title>
+
+<p>
+
+Meld will update the file comparison on the fly.
+</p>
+
+<note style="important">
+  <p>
+  Any <link xref="text-filters">text filters</link> you've defined also apply when comparing folders. Files that are identical after all of the text filters are applied are not highlighted as being different, but are shown in italics.
+  </p>
+</note>
+
+</page>
diff --git a/help/C/filtering-text.page b/help/C/filtering-text.page
new file mode 100644
index 0000000..525d8f1
--- /dev/null
+++ b/help/C/filtering-text.page
@@ -0,0 +1,121 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="text-filters">
+<info>
+  <title type="sort">2</title>
+  <link type="guide" xref="index#file-mode"/>
+  <link type="seealso" xref="file-filters"/>
+</info>
+
+<title>Filtering out text</title>
+
+<p>
+When comparing several files, you may have sections of text where differences
+aren't really important. For example, you may want to focus on changed sections
+of code, and ignore any changes in comment lines. With text filters you can
+tell <app>Meld</app> to ignore text that matches a pattern (i.e., a regular
+expression) when showing differences between files.
+</p>
+
+<note style="important">
+  <p>
+  Text filters don't just affect file comparisons, but also folder comparisons.
+  Check the <link xref="file-filters">file filtering notes</link> for more
+  details.
+  </p>
+</note>
+
+
+<section id="text-filter-creation">
+<title>Adding and using text filters</title>
+
+<p>
+You can turn text filters on or off from the the <gui>Text Filters</gui> tab in
+<gui>Preferences</gui> dialog. <app>Meld</app> comes with a few simple filters
+that you might find useful, but you can add your own as well.
+</p>
+
+<p>
+In <app>Meld</app>, text filters are regular expressions that are matched
+against the text of files you're comparing. Any text that is matched is ignored
+during the comparsion; you'll still see this text in the comparison view, but
+it won't be taken into account when finding differences. Text filters are
+applied in order, so it's possible for the first filter to remove text that now
+makes the second filter match, and so on.
+</p>
+
+<note style="tip">
+  <p>
+  If you're not familiar with regular expressions, you might want to check out
+  the Python <link href="http://docs.python.org/howto/regex.html";>Regular
+  Expression HOWTO</link>.
+  </p>
+</note>
+
+</section>
+
+
+
+<section id="text-filter-problems">
+<title>Getting text filters right</title>
+
+<p>
+It's easy to get text filtering wrong, and Meld's support for filtering isn't
+complete. In particular, a text filter can't change the number of lines in a
+file. For example, if we had the built-in <gui>Script comment</gui> filter
+enabled, and compared the following files:
+<table>
+  <tbody>
+    <tr>
+      <td>
+      <code>
+a
+b#comment
+c
+d
+      </code>
+      </td>
+      <td>
+      <code>
+a
+b
+c
+#comment
+      </code>
+      </td>
+    </tr>
+  </tbody>
+</table>
+then the lines starting with <code>b</code> would be shown as identical (the
+comment is stripped out) but the <code>d</code> line would be shown as
+different to the comment line on the right. This happens because the
+<code>#comment</code> is removed from the right-hand side, but the line itself
+can not be removed; <app>Meld</app> will show the <code>d</code> line as being
+different to what it sees as a blank line on the other side.
+</p>
+
+</section>
+
+
+<section id="text-filter-blank-lines">
+<title>Blank lines and filters</title>
+
+<p>
+The <gui>Ignore changes which insert or delete blank lines</gui> preference
+in the <gui>Text Filters</gui> tab requires special explanation. If this
+special filter is enabled, then any change consisting only of blank lines is
+completely ignored. This may occur because there was an actual whitespace
+change in the text, but it may also arise if your active text filters have
+removed all of the other content from a change, leaving only blank lines.
+</p>
+
+<p>
+You can use this option to get around some of the
+<link xref="#text-filter-problems">problems and limitations</link> resulting
+from filters not being able to remove whole lines, but it can also be useful
+in and of itself.
+</p>
+
+</section>
+
+</page>
diff --git a/help/C/index.page b/help/C/index.page
new file mode 100644
index 0000000..94cc4e9
--- /dev/null
+++ b/help/C/index.page
@@ -0,0 +1,33 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="guide"
+      id="index">
+	<info>
+		<credit type="author">
+			<name>Kai Willadsen</name>
+			<email>kai willadsen gmail com</email>
+		</credit>
+		<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
+	</info>
+
+	<title>Meld Help</title>
+
+	<section id="introduction" style="2column">
+	    <title>Introduction</title>
+	</section>
+
+	<section id="file-mode" style="2column">
+		<title>Comparing Files</title>
+	</section>
+
+	<section id="folder-mode" style="2column">
+		<title>Comparing Folders</title>
+	</section>
+
+	<section id="vc-mode" style="2column">
+		<title>Using Meld with Version Control</title>
+	</section>
+
+	<section id="advanced" style="2column">
+		<title>Advanced Usage</title>
+	</section>
+</page>
diff --git a/help/C/introduction.page b/help/C/introduction.page
new file mode 100644
index 0000000..6964256
--- /dev/null
+++ b/help/C/introduction.page
@@ -0,0 +1,23 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="introduction">
+<info>
+  <title type="sort">1</title>
+  <link type="guide" xref="index#introduction"/>
+</info>
+<title>What is Meld?</title>
+<p>
+<app>Meld</app> is a tool for comparing files and directories, and for
+resolving differences between them. It is also useful for comparing changes
+captured by version control systems.
+</p>
+
+<p>
+<app>Meld</app> shows differences between two or three files (or two or three
+directories) and allows you to move content between them, or edit the files
+manually. <app>Meld</app>'s focus is on helping developers compare and merge
+source files, and get a visual overview of changes in their favourite version
+control system.
+</p>
+
+</page>
diff --git a/help/C/keyboard-shortcuts.page b/help/C/keyboard-shortcuts.page
new file mode 100644
index 0000000..7295a59
--- /dev/null
+++ b/help/C/keyboard-shortcuts.page
@@ -0,0 +1,129 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="keyboard-shortcuts">
+<info>
+  <title type="sort">2</title>
+  <link type="guide" xref="index#advanced"/>
+</info>
+<title>Keyboard shortcuts</title>
+
+<table>
+  <title>Shortcuts for working with files and comparisons</title>
+
+  <thead>
+    <td>Shortcut</td><td>Description</td>
+  </thead>
+
+  <!-- File shortcuts -->
+  <tbody>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>N</key></keyseq></td>
+      <td><p>Start a new comparison.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>S</key></keyseq></td>
+      <td><p>Save the current document to disk.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>Shift</key><key>S</key></keyseq></td>
+      <td><p>Save the current document with a new filename.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>W</key></keyseq></td>
+      <td><p>Close the current comparison.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>Q</key></keyseq></td>
+      <td><p>Quit <app>Meld</app>.</p></td>
+    </tr>
+  </tbody>
+</table>
+
+<table>
+  <title>Shortcuts for editing documents</title>
+
+  <thead>
+    <td>Shortcut</td><td>Description</td>
+  </thead>
+
+  <tbody>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>Z</key></keyseq></td>
+      <td><p>Undo the last action.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>Shift</key><key>Z</key></keyseq></td>
+      <td><p>Redo the last undone action.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>X</key></keyseq></td>
+      <td><p>Cut the selected text or region and place it on the clipboard.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>C</key></keyseq></td>
+      <td><p>Copy the selected text or region onto the clipboard.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>V</key></keyseq></td>
+      <td><p>Paste the contents of the clipboard.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>F</key></keyseq></td>
+      <td><p>Find a string.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>G</key></keyseq></td>
+      <td><p>Find the next instance of the string.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>D</key></keyseq></td>
+      <td><p>Go to the next difference.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>E</key></keyseq></td>
+      <td><p>Go to the previous difference.</p></td>
+    </tr>
+  </tbody>
+</table>
+
+<table>
+  <title>Shortcuts for view settings</title>
+
+  <thead>
+    <td>Shortcut</td><td>Description</td>
+  </thead>
+
+  <tbody>
+    <tr>
+      <td><keyseq><key>Escape</key></keyseq></td>
+      <td><p>Stop the current comparison.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>R</key></keyseq></td>
+      <td><p>Refresh the current comparison.</p></td>
+    </tr>
+    <tr>
+      <td><keyseq><key>Ctrl</key><key>Shift</key><key>R</key></keyseq></td>
+      <td><p>Reload the current comparison.</p></td>
+    </tr>
+  </tbody>
+</table>
+
+
+<table>
+  <title>Shortcuts for help</title>
+
+  <thead>
+    <td>Shortcut</td><td>Description</td>
+  </thead>
+
+  <tbody>
+    <tr>
+      <td><keyseq><key>F1</key></keyseq></td>
+      <td><p>Open <app>Meld</app>'s user manual.</p></td>
+    </tr>
+  </tbody>
+</table>
+
+</page>
+
diff --git a/help/C/legal.xml b/help/C/legal.xml
new file mode 100644
index 0000000..86d6173
--- /dev/null
+++ b/help/C/legal.xml
@@ -0,0 +1,9 @@
+<license xmlns="http://projectmallard.org/1.0/";
+         href="http://creativecommons.org/licenses/by-sa/3.0/";>
+<p>This work is licensed under a
+<link href="http://creativecommons.org/licenses/by-sa/3.0/";>Creative Commons
+Attribution-Share Alike 3.0 Unported License</link>.</p>
+<p>As a special exception, the copyright holders give you permission to copy,
+modify, and distribute the example code contained in this document under the
+terms of your choosing, without restriction.</p>
+</license>
diff --git a/help/C/missing-functionality.page b/help/C/missing-functionality.page
new file mode 100644
index 0000000..f6f9827
--- /dev/null
+++ b/help/C/missing-functionality.page
@@ -0,0 +1,18 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="missing-functionality">
+<info>
+  <title type="sort">1</title>
+  <link type="guide" xref="index#advanced"/>
+</info>
+<title>Things that <app>Meld</app> doesn't do</title>
+
+<p>
+When <app>Meld</app> shows differences between files, it shows both files
+as they would appear in a normal text editor. It does <em>not</em> insert
+additional lines so that the left and right sides of a particular change
+are the same size. There is no option to do this.
+</p>
+
+
+</page>
diff --git a/help/C/resolvingconflicts.page b/help/C/resolvingconflicts.page
new file mode 100644
index 0000000..e20bbf9
--- /dev/null
+++ b/help/C/resolvingconflicts.page
@@ -0,0 +1,29 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="resolving-conflicts">
+<info>
+  <title type="sort">0</title>
+  <link type="guide" xref="index#vc-mode"/>
+</info>
+<title>Resolving merge conflicts</title>
+
+<p>
+One of the best uses of <app>Meld</app> is to resolve conflicts that occur
+while merging different branches.
+</p>
+
+<p>
+For example, when using <app>Git</app>, <cmd>git mergetool</cmd> will start
+a 'merge helper'; <app>Meld</app> is one such helper. If you want to make
+<app>git mergetool</app> use <app>Meld</app> by default, you can add
+</p>
+<code>
+[merge]
+    tool = meld
+</code>
+<p>
+to <file>.git/gitconfig</file>. See the <app>git mergetool</app> manual for
+details.
+</p>
+
+</page>
diff --git a/help/C/startingmeld.page b/help/C/startingmeld.page
new file mode 100644
index 0000000..d34870b
--- /dev/null
+++ b/help/C/startingmeld.page
@@ -0,0 +1,38 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="command-line">
+<info>
+  <title type="sort">2</title>
+  <link type="guide" xref="index#advanced"/>
+</info>
+<title>Command line usage</title>
+
+<p>
+If you start <app>Meld</app> from the command line, you can tell it what to do when it starts.
+</p>
+<p>
+For a two- or three-way <link xref="file-mode">file comparison</link>, start <app>Meld</app> with
+<cmd>meld <var>file1</var> <var>file2</var></cmd> or
+<cmd>meld <var>file1</var> <var>file2</var> <var>file3</var></cmd> respectively.
+</p>
+
+<p>
+For a two- or three-way <link xref="directory-mode">directory comparison</link>, start <app>Meld</app> with
+<cmd>meld <var>dir1</var> <var>dir2</var></cmd> or <cmd>meld <var>dir1</var> <var>dir2</var> <var>dir3</var></cmd>.
+</p>
+
+<p>
+You can start a <link xref="vc-mode">version control</link> comparison by just
+giving a single argument; if that file or directory is managed by a
+<link xref="vc-supported">recognized version control system</link>, it will
+start a version control comparison on that argument. For example,
+<cmd>meld .</cmd> would start a version control view of the current directory.
+</p>
+
+<note>
+<p>
+Run <cmd>meld --help</cmd> for a list of all command line options.
+</p>
+</note>
+
+</page>
diff --git a/help/C/vc-supported.page b/help/C/vc-supported.page
new file mode 100644
index 0000000..83d6ea8
--- /dev/null
+++ b/help/C/vc-supported.page
@@ -0,0 +1,34 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="vc-supported">
+<info>
+  <title type="sort">1</title>
+  <link type="guide" xref="index#vc-mode"/>
+</info>
+<title>Supported version control systems</title>
+
+<p>
+<app>Meld</app> supports a wide range of version control systems:
+</p>
+
+<list>
+  <item><p>Arch</p></item>
+  <item><p>Bazaar</p></item>
+  <item><p>Codeville</p></item>
+  <item><p>CVS</p></item>
+  <item><p>Fossil</p></item>
+  <item><p>Git</p></item>
+  <item><p>Mercurial</p></item>
+  <item><p>Monotone</p></item>
+  <item><p>RCS</p></item>
+  <item><p>SVK</p></item>
+  <item><p>SVN</p></item>
+</list>
+
+<p>
+Less common version control systems or unusual configurations may not be
+properly tested; please report any version control support bugs to <link
+href="https://bugzilla.gnome.org/";>GNOME bugzilla</link>.
+</p>
+
+</page>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]