Easily edit example files

[nmattia]

It would be great to have shorthand to edit example files. For instance:

$ eg -c <c> edit <program>

would be equivalent to

$ $EDITOR <c>/<program>.md

(This particular syntax might be a bit ambiguous)

[srsudar]

Hmm that is an interesting thought. Are you wanting this to edit only custom directories (as shown with -c <c>), or are you also interested in editing the examples that come with eg?

[nmattia]

ultisnips, the vim plugin, offers commands to jump straight to snippet edition. I have always found it very convenient. I was surprised not to find such a command with eg.

Whether or not (and how) to allow users to edit the "official" examples (i.e. those that come with eg) is a good question. I think it would be interesting. This might inspire people to hack and improve the snippets (which are great already, by the way).

I do not know how eg looks up the example files but assume it will look for CUSTOM_DIR first, and then EXAMPLES_DIR. If this is indeed what happens, "official" example files could be copied from EXAMPLES_DIR to CUSTOM_DIR first upon edition. Then the "custom" copy could be opened with the editor.

This means the following commands would be more or less equivalent:

$ eg -c <custom> -e <examples> edit <program>

$ (   [ -e <custom>/<program>.md ]          \
  ||  cp <examples>/<program>.md <custom> ) \
  ;  $EDITOR <custom>/<program>.md

So if we already have a such a custom example, we edit it. If we don't, we try to copy it from the official examples. If the copy works, we edit the copy. If the copy doesn't work (there is no official example) we start a new custom example.

(of course I don't mean it to work only if there user supplies the -c and -e parameters, it's just to clarify what I mean by <custom> and <examples>.)

[srsudar]

Custom files are currently more supplements than full replacements. If you have a custom file its contents are shown first, with the stock file content below it. For this reason I don't think copying the original file content over would be a great fit, as you'd end up with the same content displayed twice.

The benefit of the system as-is (or at least the way I made it this way), is that it is a place to put common personal commands that you might use frequently but that aren't appropriate for (or haven't yet been rolled into) the stock examples.

Thinking about it some more, I prefer the idea of having the edit functionality edit or create a custom file for the command. This seems like a very elegant shortcut.

Editing the original examples is possible with a custom git-based install but could run into write permissions issues if installed via pip. More importantly, editing only the custom file seems more philosophically in line with eg. bropages is a tool similar to eg that emphasizes an alternative more collaborative approach, allowing you to edit and vote on global examples from the command line. This is neat, but not something I want to include in eg.

I like the idea of having an edit shortcut for custom files, however, and will work on incorporating it.

[nmattia]

Problem solved then. Great, thanks a lot! Let me know how I can help, though my python knowledge is limited at best.

[srsudar]

I'm almost done with this, but it brought up a usability question that I'm yet to implement. If you don't have a custom-dir option set in your .egrc (and I'm assuming most people do not, even though I do), it isn't immediately obvious where to save your custom example files.

I'm leaning toward just plopping them in a directory of my choosing, like ~/.eg/. If I have to create this directory, I'll show a warning people have to hit enter to get through, like:

No custom-dir has been set in your .egrc. A default directory will be created at ~/.eg/.
Your custom examples will be saved there. Is this ok?
(Y/n)

If you were prefer this directory to exist somewhere else, set the value in your .egrc.
A minimal .egrc accomplishing this should be saved as ~/.egrc and would look like
this:

[eg-config]
custom-dir = ~/path/to/custom_files

Does that seem reasonable to you?

I've also decided to resolve an editor command in the following order: .egrc, $VISUAL, $EDITOR. This is the same general resolution process git follows, which seems reasonable to me.

[srsudar]

Hmm, better still might be something like:

You do not have a custom directory set in your .egrc. Your custom examples will be
saved in ~/.eg/ and this location will be stored as your custom directory in your .egrc.

Ok? [Y/n]

[nmattia]

I like the second solution, however in practice I think I would prefer if the tool I'm using doesn't tamper with my settings and just uses a default directory. The main reason being that I might have comments in that file as well, in a very specific order, etc (e.g. for housekeeping reasons). Does that make sense? On the other hand it doesn't apply to me directly since I do have a custom-dir entry, and it happens to be set to ~/eg/. I guess ~/.eg is a better default, since it aligns with ~/.vim, ~/.i3, etc.

Either way, thanks for implementing this so quickly!

[srsudar]

Your reasoning does make sense. My thought was that if you're trying to edit something it would be frustrating to be told you have to first set up a bunch of configuration. Providing a sensible default seems like a reasonable shortcut, especially since the egrc syntax is not immediately obvious.

…

On Fri, Jan 20, 2017, 5:03 PM Nicolas Mattia ***@***.***> wrote: I like the second solution, however in practice I think I would prefer if the tool I'm using doesn't tamper with my settings and just uses a default directory. The main reason being that I might have comments in that file as well, in a very specific order, etc (e.g. for housekeeping reasons). Does that make sense? On the other hand it doesn't apply to me directly since I *do* have a custom-dir entry, and it happens to be set to ~/eg/. I guess ~/.eg is a better default, since it aligns with ~/.vim, ~/.i3, etc. Either way, thanks for implementing this so quickly! — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#65 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AGEWAZHIl64tRUTvQfP5_0bUXi48jfgPks5rUVlogaJpZM4Ljmrb> .

[srsudar]

It looks like by default using ConfigParser to write to a file does so in a potentially destructive way, at a minimum removing comments and likely also with the potential to change order.

I'll probably implement the way I first laid out, saving it in a default location and explaining what a minimal egrc would be. For most people this would probably be sufficient.

[srsudar]

I'm back to thinking that you're probably right, better not to tamper with people's setups. If you don't have a custom directory set, I'll likely just print a warning and an example egrc and do nothing.

[srsudar]

I just pushed some some new changes to master that handle this. If you could clone and check it with your own setup, that would be great. I've tested with python 2.7 and 3.4 and everything looks good.

[nmattia]

Nice, works like a charm!

pip version: 8.1.2
python version: 2.7.12
eg version: 0.1.4
egrc:

[eg-config]
custom-dir = ~/eg

[himat]

This should be added to the readme. It doesn't mention this easy way to edit an eg page at all.
This was the main feature preventing me from instantly installing this, and I had to come here and search for an issue to see if it had been brought up at all.

[srsudar]

Good point. I added it to the configuration section.