search

preservim / vim-textobj-quote

Use ‘curly’ quote characters in Vim
Other
123 stars 6 forks source link

Generate native Vim documentation #6

Closed reedes closed 3 years ago

reedes commented 9 years ago

Using https://github.com/FooSoft/md2vim or similar.

alerque commented 4 years ago

Hey look at this there is already an issue open to track this!

See #22 for where this came up again.

@telemachus You might look into md2vim. I don't have a strong preference since (per my comment here) I don't see the help docs overlapping very much the README and the help docs have a ton of custom formatting options. I would rather see full featured internal docs if auto-generating them means compromising on that, but otherwise it could go either way.

telemachus commented 4 years ago

@alerque Sounds good. I had already installed md2vim, and I used it on the current README to give me a jump start. I need to read a bit about standards for vim documentation, and then I can start editing both the documentation and the README. I agree with you that the README should be shorter, and the documentation should have the bulk of the details.

telemachus commented 4 years ago

@alerque I have a draft: https://gist.github.com/telemachus/a60080ff1e8cca25150a15a0f803f7f6.

You can see how it looks live pretty easily.

  1. mkdir vim-textobj-quote/doc on your system
  2. Download the gist and save it in that directory as textobj-quote.txt.
  3. Open vim, run helptags ALL, and then try help textobj-quote.

The draft is pretty much done. I can proof it a little further and make a pull request, but I wanted to ask you a question first. Would you prefer what I have here—which is basically the README turned into a help file—or are you okay with me reorganizing and rewriting sections of the help? I ask because I was inclined to make more significant changes to the documentation. (I think it can be clearer.) But I won't do that if you prefer to leave it as is.

alerque commented 4 years ago

I would be fine with having sections rewritten for clarity, but I would do it in two steps. Have one commit that basically just shuffles the readme stuff over to help docs, then further commits in the same PR that added your copy-editing/rewriting. That will make them easier to review.

Feel free to go ahead and open a PR in Draft mode for renew along the way. You can always keep working on it and that would be the easiest way to proof.

telemachus commented 4 years ago

Okay, sounds good. I'm not familiar with draft mode, but I'll take a look.