Manual updates

Main development forum.

Manual updates

Postby denisbradford » Mon Apr 06, 2009 3:18 pm

It's been a while since I touched the Help (about 2.11, I think!). I haven't forgotten WinMerge, in fact I use it all the time at work (where they make me use Windows). Even though most of your changes have been bug fixes (plus a few doc changes), I see some of the stuff I wrote last year is out of date. If nobody objects, I'd like to catch up a little and resume submitting patches as I did last year.

To get started, I'd like to post under this topic a list of changes (from the changelogs) that might have a doc impact. A first pass indicates there may be two dozen or more changes, none of them huge. I'll follow up with questions where I need help with some items. Otherwise, you can just track what I'm doing if you like, and jump in with suggestions or corrections. Let me know if you prefer a different process.
denisbradford
 
Posts: 46
Joined: Thu Sep 25, 2008 12:24 pm
Location: U.S.A.

Re: Manual updates

Postby kimmov » Tue Apr 07, 2009 2:59 pm

Yes, changes in 2.12 stable since your last patches aren't so big. Maybe the most visible change is adding tree-mode view for the folder compare. And having all unique items shown in the results.

For 2.13/2.14 there will be some changes but nothing "big". I hope we can branch for stable before the summer so there is maybe month or two still time for getting new features and GUI changes in. I don't expect anything big but probably some clarifications to options dialog and couple of other places.

Looking at bug list I see two these manual-related items:
  • #2714147 Manual: need to improve lin-line difference documentation
  • #2051864 "Match Similar Lines" option is Undocumented
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Manual updates

Postby denisbradford » Mon Apr 13, 2009 8:06 pm

After combing through the release notes and change list and spending some time with 2.12.2, I've compile a list of proposed doc changes. No reply needed unless you object to an item or I missed something important. I just want to let everyone know what I'm doing before I start submitting patches. It will be a week or so before I get started anyway.

Hmm, looks like I'm not authorized to attach, so I'll just paste it here - sorry it's so long:

=====================================
Bug #2714147 The systax for highlightning is not correct documented.
Describe line differences in 'Comparing and merging files'.

=====================================
Bug #2714147 In Options / Compare, there is a checkbox to
enable/disable a feature called "Match Similar Lines".

In 'Options and configuration', document Match similar lines.

=====================================
Suggestion from user forum: Where are the line filters saved?

In 'Using Filters', document that line filters are stored in the
registry. The path is:
HKEY_CURRENT_USER\Software\Thingamahoochie\WinMerge\LineFilters

=====================================
Patch #2714968 Disable folder compare tree-view by default

Document tree mode in 'Comparing and merging folders'.

=====================================
Patch #2479804 More accurate visible area indicator in location pane

Zoom feature not implemented, so no change to functional
description. Possibly change some screen shots that feature
location pane.

=====================================
Patch #2433648 New options page for Shell Integration options
In 'Options and configuration', add Shell Integration section,
moving some items from System options topic.

Throughout manual, find references to System options page, replace
as necessary.

=====================================
Patch #2354125 Allow reloading the file if it has been changed on the
disk behind WinMerge
Document in 'Comparing and merging files > Rescanning files'

=====================================
Patch #2327424 Add option to show Open-dialog on WinMerge startup
Document in 'Options and configuration'.

=====================================
Patch #2435175 Installer: Option to add WinMerge to system path

In 'Using the installer', doc new option, 'Add WinMerge folder to your system path'.
=====================================
Patch #2189315 Add shell context menu to folder compare context menu

* Add Shell menu option in 'Options and configuration>
Shell Integration section'.

* Describe using this capability in Comparing and merging folders.

* Disambiguate use of "shell integration" throughout the manual
(for example, in 'Opening files and folders') to distinguish
shell integration from adding WinMerge commands.

* Mention in 'Using WinMerge with other tools'.

=====================================
Patch #2175736 General compare status for files (not known if text/binary)
Document in 'File and folder icons'.

=====================================
Patch #2185302 Change icons for the new general compare status
Update screen shots as required throughout the manual.

=====================================
Patch #2129095 Installer: create backup of ClearCase config file

Add note to 'Options and configuration > Version Control options'
describing how to remove ClearCase integration. Reference in
'Integration with version control tools' and 'Getting and
installing WinMerge > Using the installer'.
=====================================
Patch #2082774 Use external editor to edit file filters
No doc change: already doc'ed that way, erronously until now :-P

=====================================
Patches #2029275, #2030359 Add -u commandline parameter as alternative to -ub
In 'Command line' add {u|ub} argument to syntax.
Add missing documentation for ub.

=====================================
Changelog:
In 'Locale support' add Ukrainian, Brazilian.

=====================================
Miscellaneous doc problems:

-------------------------------
Compare_files

menuchoice/guimenu is getting rendered with a plus sign instead of an
arrow.

-------------------------------
Add links to Shortcut_keys in places where we mention keyboard shortcuts.

-------------------------------
In the CHM toc, 'Comparing files' and 'Merging files' have book icons,
but they navigate to sections in 'Overview of file comparing and
merging'. Strange. Should they topics?

-------------------------------
'Add to explorer context menu': explorer should be Explorer.

-------------------------------
In 'Options and configuration'
Clean up 'By default, Notepad is configured as the default external
editor'

-------------------------------
In 'Comparing and merging folders', link to 'Browsing unique folders' is broken.

-----------------------------
In 'Using the installer > Select Additional Tasks'
* Delete 'Integrate with ClearCase' option.
* Change 'shortcut' to 'icon' in last two options.
* Describe Filters and Plugins better.

-----------------------------
Tools > Customize columns
Mention new menu item to open Display Columns dialog in 'Adding, removing, and reordering columns'.

-----------------------------
In CHM index, 'Refresh function' link is broken.
Index needs entries for 'navigation functions', 'merge functions'.

-------------------------------
manual-authoring.html duplicates this line:
Use the active voice, which emphasizes the person or thing doing the action. It is more direct and personal than the passive voice, which can be confusing or sound formal.

=====================================

No plan to doc:
Patch#2036603: Hex editor.
Patch#2638608: Don't see changes to Plugin Settings > Prediffer Settings.
Patch#2445749: Allow multiple file compare documents by default.

These are apparently not implemented yet in 2.12.2.0 GUI, as far as I could tell.
denisbradford
 
Posts: 46
Joined: Thu Sep 25, 2008 12:24 pm
Location: U.S.A.

Re: Manual updates

Postby kimmov » Mon Apr 13, 2009 11:17 pm

denisbradford wrote:Suggestion from user forum: Where are the line filters saved?

In 'Using Filters', document that line filters are stored in the
registry. The path is:
HKEY_CURRENT_USER\Software\Thingamahoochie\WinMerge\LineFilters

Referring to registry keys in user documentation is a bit dangerous. I don't want to encourage anybody to edit filters using regedit. We should just say the line filters are currently stored to registry.

denisbradford wrote:Patch #2479804 More accurate visible area indicator in location pane

Zoom feature not implemented, so no change to functional
description. Possibly change some screen shots that feature
location pane.

Probably doesn't need any change at all.

denisbradford wrote:Patch #2354125 Allow reloading the file if it has been changed on the
disk behind WinMerge
Document in 'Comparing and merging files > Rescanning files'

Yes, this was important change, requested by lots of users.

denisbradford wrote:Patch #2189315 Add shell context menu to folder compare context menu

* Add Shell menu option in 'Options and configuration>
Shell Integration section'.

* Describe using this capability in Comparing and merging folders.

* Disambiguate use of "shell integration" throughout the manual
(for example, in 'Opening files and folders') to distinguish
shell integration from adding WinMerge commands.

* Mention in 'Using WinMerge with other tools'.

I (still) have some mixed feelings about this feature. It think it is great for functionality, allowing things like accessing version control functionality from WinMerge context menu. But I think it also can add lots of confusion. We kind of use shell inside WinMerge, but don't react to the actions in any way inside WinMerge. If user deletes the file, it does not get deleted from WinMerge GUI.

Maybe we should have some Advanced tips and tricks-section in manual and add this kind of things there?

denisbradford wrote:'Add to explorer context menu': explorer should be Explorer.

Or even Windows explorer?

denisbradford wrote:Tools > Customize columns
Mention new menu item to open Display Columns dialog in 'Adding, removing, and reordering columns'.

Don't remember if this is already mentioned in docs but column selection dialog can also be opened by right-clicking column headers.

denisbradford wrote:No plan to doc:
Patch#2036603: Hex editor.
Patch#2638608: Don't see changes to Plugin Settings > Prediffer Settings.
Patch#2445749: Allow multiple file compare documents by default.

These are apparently not implemented yet in 2.12.2.0 GUI, as far as I could tell.

Hex editor is still experimental feature only in experimental/beta versions. Patch#2445749 is in 2.12, but it is only a change in default value for option.
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Manual updates

Postby denisbradford » Tue Apr 14, 2009 7:26 pm

>Patch#2445749 is in 2.12, but it is only a change in default value for option.

I don't see the change in 2.12.2.0: 'Options>General>Enable multiple compare windows for File compare' is off by default. I hit Reset, too.
denisbradford
 
Posts: 46
Joined: Thu Sep 25, 2008 12:24 pm
Location: U.S.A.

Re: Manual updates

Postby kimmov » Tue Apr 14, 2009 7:35 pm

denisbradford wrote:>Patch#2445749 is in 2.12, but it is only a change in default value for option.

I don't see the change in 2.12.2.0: 'Options>General>Enable multiple compare windows for File compare' is off by default. I hit Reset, too.

The change definitely is in the code. Just checked.

But the problem here is that the general options don't have reset-button for all options, only for those message boxes. So only way to reset general options is to remove WinMerge settings from registry.
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Manual updates

Postby denisbradford » Fri Apr 24, 2009 12:49 pm

I'm trying to improve the doc on line differences. I have enabled moved block detection, but can't get the Moved difference color to work.
I'm trying things like this:


Code: Select all
File 1                File 2
------                -------
I ran three paces.    I ran three paces.
Jiminy Cricket.       I ran two paces.
I ran two paces.      Jiminy Cricket.


Lines 2 and 3 are identical, but in different places. Shouldn't this be a move?
If not, why not? Can you give me a simple example of a move?

Thanks,
Denis
denisbradford
 
Posts: 46
Joined: Thu Sep 25, 2008 12:24 pm
Location: U.S.A.

Re: Manual updates

Postby kimmov » Fri Apr 24, 2009 1:13 pm

Block in feature name refers to differences. That is, it handled whole differences, not single lines.

So in practice it detects differences where all lines in difference have been moved to another place in the file. If you edit those lines you move WinMerge cannot detect them as moved. Lines must match exactly.

I'm bit unsure of usability of this whole feature. There are several basic problems and nobody has touched the code for years. So this is one candidate feature for complete removal.
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Manual updates

Postby denisbradford » Fri May 01, 2009 6:38 pm

Re bug: 2714147 Manual: need to improve lin-line difference documentation

I've updated three topics in the manual to address this bug. The changes are extensive enough that I think some review is needed, please. I'm attaching an archive containing the sources and generated HTML for the three modified topics, plus a README listing the changes. I hope this makes it easy for you to review the changes, and reply with any feedback.

Thanks,
Denis
Last edited by denisbradford on Thu May 07, 2009 11:56 am, edited 1 time in total.
denisbradford
 
Posts: 46
Joined: Thu Sep 25, 2008 12:24 pm
Location: U.S.A.

Re: Manual updates

Postby denisbradford » Thu May 07, 2009 11:55 am

Update: Any replies to this message should be in bug 2714147, not here. I've moved the discussion there.

denisbradford wrote:Re bug: 2714147 Manual: need to improve lin-line difference documentation

I've updated three topics in the manual to address this bug. The changes are extensive enough that I think some review is needed, please. I'm attaching an archive containing the sources and generated HTML for the three modified topics, plus a README listing the changes. I hope this makes it easy for you to review the changes, and reply with any feedback.

Thanks,
Denis
denisbradford
 
Posts: 46
Joined: Thu Sep 25, 2008 12:24 pm
Location: U.S.A.

Next

Return to Developers

Who is online

Users browsing this forum: No registered users and 1 guest