Ticket #3742 (accepted enhancement)

Opened 2 years ago

Last modified 7 months ago

Update to the comments at the start of mc.ext

Reported by: mc-hobbit Owned by: zaytsev
Priority: minor Milestone: 4.8.22
Component: mc-core Version: master
Keywords: Cc:
Blocked By: Blocking:
Branch state: no branch Votes for changeset:

Description

I would like to propose using the attached file at the start of the mc.ext file. Changes include:

  • Update the formatting to put keywords, their description, and additional comments on lines by themselves, following established conventions used by man pages
  • Remove references to version 3.0 (version 4.0 was released nearly twenty years ago)
  • Use "i.e." (Latin, "id est", or "that is") and "e.g." ("example") as appropriate
  • Update the English in many places

Attachments

mc.ext.txt (4.6 KB) - added by mc-hobbit 2 years ago.
Proposed update to mc.ext comments
0001-Ticket-3681-and-3742.patch (10.2 KB) - added by mc-hobbit 2 years ago.
Patch for tickets 3681 and 3742
0001-Ticket-3742-patch-2.patch (2.9 KB) - added by mc-hobbit 23 months ago.
Remove reference to $MC_* variables and change 'temporal' to 'temporary'
0001-Ticket-3742-patch-3.patch (686 bytes) - added by mc-hobbit 23 months ago.
Remove '#' from text "KEYWORD is one of the # following"

Change History

Changed 2 years ago by mc-hobbit

Proposed update to mc.ext comments

comment:1 Changed 2 years ago by mc-hobbit

  • Summary changed from Update to the commnts at the start of mc.ext to Update to the comments at the start of mc.ext

comment:2 Changed 2 years ago by zaytsev-work

Could you please supply a patch at least in form of git --diff? Better even would be to checkout the development tree (git clone ...), make your changes, commit them (git commit -a -s) and attach the patch produced with git format-patch HEAD~. This will also provide us with correct authorship information for credits.

comment:3 Changed 2 years ago by andrew_b

Related to #3681.

comment:4 Changed 2 years ago by mc-hobbit

Yes, I'll do the checkout, update, and commit, and attach the diff (I'm assuming you want it attached to the bug.) This will take me a few days as I'm also busy with other stuff. As part of my changes I'll include the comment noted in bug 3681.

Changed 2 years ago by mc-hobbit

Patch for tickets 3681 and 3742

comment:5 Changed 2 years ago by zaytsev

Ticket #3681 has been marked as a duplicate of this ticket.

comment:6 Changed 2 years ago by zaytsev

  • Owner set to zaytsev
  • Status changed from new to accepted
  • Milestone changed from Future Releases to 4.8.19

comment:7 Changed 2 years ago by zaytsev

Hi, I've checked your edits, and in general it looks very good, but

  • this local temporal file -> this local temporary file?
  • it seems to me that the part about environment variables is now wrong

You wrote:

	# COMMAND is any one-line shell command, with the following substitutions: 
...
	#    %p or $MC_EXT_BASENAME 

In fact, $MC_EXT_BASENAME will NOT be substituted in the COMMAND, but rather an environment variable MC_EXT_BASENAME will be set and when the COMMAND is executed, it can pull the value of %p out of this environment variable. This was reflected in the old text, however bad it was, but in the new text the meaning is completely lost.

It would be great if you could fix that, so that I can commit the patch... You can edit the file and then git add ... & git commit --amend update your commit.

comment:8 Changed 2 years ago by mc-hobbit

I'll double-check the documentation and fix or clarify as needed.

Changed 23 months ago by mc-hobbit

Remove reference to $MC_* variables and change 'temporal' to 'temporary'

comment:9 Changed 23 months ago by mc-hobbit

I've removed the references to the MC_* variables. I also changed temporal to read temporary, although I note the original phrasing has been there for at least twenty years. (I found a copy of the source for mc-3.2.11 at http://archive.kernel.org/redhat-archive/redhat/linux/4.2/en/os/i386/SRPMS/mc-3.2.11-2.src.rpm. The mc.ext.in file is dated 1 October 1996.)

Changed 23 months ago by mc-hobbit

Remove '#' from text "KEYWORD is one of the # following"

comment:10 in reply to: ↑ description Changed 19 months ago by andrew_b

Replying to mc-hobbit:

  • Remove references to version 3.0 (version 4.0 was released nearly twenty years ago)

In addition to that, we should remove references to version 3.0 in error messages: src/filemanager/ext.c:832 and src/filemanager/ext.c:853.

comment:11 Changed 13 months ago by zaytsev

  • Milestone changed from 4.8.20 to 4.8.21

comment:12 in reply to: ↑ description Changed 11 months ago by jack99999

Replying to mc-hobbit:

  • Use "i.e." (Latin, "id est", or "that is") and "e.g." ("example") as appropriate

many people get confused by, or do not understand, latin abbreviations. it is better to stick with "that is" and "for example".

you can easily find many hits about the confusion if you search for 'i.e. and e.g. confusion'.

here are some snippets just to get you going:

from http://www.telegraph.co.uk/news/2016/07/23/government-bans-latin-abbreviations-on-its-websites-to-avoid-con/

The government is to ban all Latin abbreviations on all its websites to avoid
confusing non-English speakers, it has been announced.

Phrases such as etc, ie, and eg will be phased out from all GOV.UK sites because
foreign speakers find them “difficult to read”.

from https://insidegovuk.blog.gov.uk/2016/07/20/changes-to-the-style-guide-no-more-eg-and-ie-etc/

eg, etc and ie

‘eg’ can sometimes be read aloud as ‘egg’ by screen reading
software. Instead use ‘for example’ or ‘such as’ or 'like' or ‘including’ -
whichever works best in the specific context.

‘etc’ can usually be avoided. Try using ‘for example’ or ‘such as’ or
‘including’. Never use ‘etc’ at the end of a list starting with ‘for
example’ or ‘such as’ or ‘including’.

‘ie’ - used to clarify a sentence - isn’t always well understood. Try
(re)writing sentences to avoid the need to use it. If that isn’t possible,
use an alternative such as ‘meaning’ or ‘that is’.

from http://www.quickanddirtytips.com/education/grammar/ie-versus-eg

Misusing these two abbreviations is one of the top five mistakes I used to see
when editing technical documents. There's so much confusion that in some of the
drafts I got back from clients they had actually crossed out the right
abbreviation and replaced it with the wrong one.

from https://www.thoughtco.com/commonly-confused-latin-abbreviations-1692754

These days, a safe rule for using Latin abbreviations (such as etc., e.g., et
al., and i.e.) is not to use them at all.

comment:13 Changed 7 months ago by zaytsev

  • Milestone changed from 4.8.21 to 4.8.22
Note: See TracTickets for help on using tickets.