Readme text?

Main development forum.

Readme text?

Postby kimmov » Tue Nov 04, 2008 10:45 pm

I think we should modify / modernize the readme text a bit. The problem is this is translated text (having several translations) so we must try to minimize the times we modify it. Lets collect things to change in this thread before submitting actual patches.

This file is many times the first document about WinMerge users see (it is shown by the installer). So we should keep the content up to date and correct. And perhaps we should have more introductory content. What is WinMerge etc.

Couple of first items to change:
  • link to forum should point to these new forums
  • in latest releases manual is always installed locally
  • scripts aren't so important that they need to be mentioned in this file

Other changes?
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Readme text?

Postby denisbradford » Thu Nov 06, 2008 8:58 pm

I've done an edit. I can post the patch, if you like.
denisbradford
 
Posts: 46
Joined: Thu Sep 25, 2008 12:24 pm
Location: U.S.A.

Re: Readme text?

Postby kimmov » Thu Nov 06, 2008 9:23 pm

denisbradford wrote:I've done an edit. I can post the patch, if you like.


Yes, please submit a patch.
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Readme text?

Postby denisbradford » Fri Nov 07, 2008 3:16 pm

kimmov wrote:
denisbradford wrote:I've done an edit. I can post the patch, if you like.


Yes, please submit a patch.


OK, submitted patch 2234689
denisbradford
 
Posts: 46
Joined: Thu Sep 25, 2008 12:24 pm
Location: U.S.A.

Re: Readme text?

Postby kimmov » Fri Nov 07, 2008 4:35 pm

denisbradford wrote:OK, submitted patch 2234689


[Please use the tracker shortcut links as mentioned in "About this forum post". Makes it a lot easier to go to mentioned tracker items. So this is Patch #2234689]

Thanks, looks definitely better than the current version. Some comments in no particular order:

I think it would be good to always end URL with "/". Unless the URL has parameters or filename at the end.

There is no "--help" switch for the WinMerge executable. But /? switch opens the manual for command line help. Previously we did show dialog listing most common switches but decided it is better to just open the manual with full help.

When talking about 7-zip plugin we refer to downloading it from WinMerge.org. I think we should use the URL http://winmerge.org/downloads/ when referring to downloads as the main page just has a link to latest version installer.

This is more a question to Tim: can we have shortcut links to bug/feature request trackers also? I think it would be better to tell users to go to http:/winmerge.org/bugs/ than cryptic direct link to sf.net tracker. And perhaps for forums too? You can also start a new thread about the new redirects if you want to...

I think we should not anymore refer to RFE in our documents. Sourceforge renamed the trackers to "Feature Requests" and so the RFE isn't really visible in sf.net anymore. It just confuses people.
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Readme text?

Postby gerundt » Sat Nov 08, 2008 10:49 pm

kimmov wrote:This is more a question to Tim: can we have shortcut links to bug/feature request trackers also? I think it would be better to tell users to go to http:/winmerge.org/bugs/ than cryptic direct link to sf.net tracker. And perhaps for forums too? You can also start a new thread about the new redirects if you want to...


Folder redirects like http:/winmerge.org/bugs/ are no problem for me! For subdomain redirects like forums.winmerge.org I need access to the 1and1 web config but I have unfortunately only a FTP access. :roll:
gerundt
Site Admin
 
Posts: 193
Joined: Wed Sep 24, 2008 8:47 am
Location: Germany

Re: Readme text?

Postby denisbradford » Mon Nov 10, 2008 2:51 pm

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

Re: Readme text?

Postby kimmov » Mon Nov 10, 2008 7:48 pm

Yes, that looks very good already.

The Help topics are also available as HTML pages on the WinMerge Web site. You can browse WinMerge Help at http://winmerge.org/docs/manual/.


For me the first sentence sounds a bit weird though? I mean that "as HTML pages" - Wouldn't "as HTML version" or something like that be a better way to say it? As for me it now sounds we have some collection of HTML pages...

If you cannot install the 7-Zip tool for any reason, you can use the 7-zip plugin installer to install only the files required for archive file support. Note that this option enables only archive support for WinMerge. It DOES NOT enable you to run 7-Zip standalone.


Here I'm wondering about last two sentences. This really does not help the user who is wondering what to do when one wants to get the archive support working. Perhaps it would be better to just point user to web manual about archive support installing? I know, this is originally my text...
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Readme text?

Postby denisbradford » Tue Nov 11, 2008 2:11 pm

Rewriting the two offending passages:

You can also browse the HTML version of WinMerge Help at http://winmerge.org/docs/manual/.

If you cannot install the 7-Zip tool for any reason, you can use the 7-zip plugin installer to install only the files required for archive file support. See the Help topic, "7-Zip and archive support" for details.

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

Re: Readme text?

Postby gerundt » Tue Nov 11, 2008 2:31 pm

Btw, could we maybe put lines under the headings?

Code: Select all
WINMERGE

...

Quick start:
------------
To learn how to perform basic operations after installing WinMerge, click
Help>WinMerge Help and navigate to the Quick start topic.  Or, go to the Web
version at http://winmerge.org/docs/manual/QuickStart.html.

WinMerge Help:
--------------
WinMerge Help is installed locally as a Microsoft HTML Help file, WinMerge.chm,
when you install WinMerge. To open Help, click Help>WinMerge Help or press F1 in
the WinMerge window. On the command line, run the WinMerge executable with the
/? help switch.

...


I think this more eye-catching! :mrgreen:
gerundt
Site Admin
 
Posts: 193
Joined: Wed Sep 24, 2008 8:47 am
Location: Germany

Next

Return to Developers

Who is online

Users browsing this forum: No registered users and 2 guests

cron