Thursday, February 27, 2014

Re: README.md to a doc?

2014-02-27 03:45, Tim Johnson skrev:
> * Tim Johnson <tim@akwebsoft.com> [140226 16:44]:
>> * Adnan Zafar <adnanjzafar@gmail.com> [140226 16:32]:
>>> Hi Tim,
>>>
>>> Just leave the file as it is or delete it. Plugin authors provide
>>> files like that to provide information on GitHub pages for example. If
>>> you're installing the plugin using Pathogen or Vundle or one of the
>>> others, everything should be set up to just ignore it. If you're
>>> installing manually, you can just delete the file.
>>
>> I was wondering if there were a built-in way to make a
>> doc-compatible .txt file out of it. It sounds like there isn't.
>>
>> I wouldn't mind spending a little time "marking up" a README.md to
>> make it doc-compatible. I think that there are adequate
>> instructions in :h helptag
> Turns out that in a general case a README.md file can be
> converted to a doc .txt file in just a few minutes.

If you are writing the file yourself it can be marked up as
*both* Markdown and Vim halp without looking *too* strange when
rendered as either. You can see an example here:

<https://github.com/bpj/vim-ToggleKeymap/blob/master/doc/ToggleKeymap.txt>

It's a bit on the extreme side, and I'm afraid it looks just a
little more strange rendered as Vim help than as Markdown!

(Don't look at the code -- it's my first attempt ever at writing
a plugin and I'm sure I've overlooked a ton of things --
including making a SwEnglish translation error when naming it!)

I've been thinking of writing a Pandoc filter -- not knowing
Haskell and not being prepared to tackle the learning curve
writing a filter in Perl is at least feasible to me --
which produces Vim help format when using plain text as target
format. I might still do that -- especially since I'm apparently
not the only one who would find it useful!

It would just do three to five things:

1. Enclose the text of headers which don't contain any whitespace
in asterisks, i.e. `# foo-bar` becomes `# *foo-bar*` with a
vimhelp
tag target, while `# foo bar` remains unchanged because of
the period.

2. Turn links like `[replace virtual characters](URL "vim:gr")`
(i.e. where the title string matches `/^vim:(\S+)$/`) into
`replace virtual characters (|gr|)`.

3. Make sure the URLs of *other* non-local links actually show
up in the output.

4. Maybe recognise links to <http://vimdoc.sourceforge.net>
and do the Right Think with them.

5. Maybe enclosing emphasized text in curlies.
(BIG maybe, but I abhor semantic loss!)

However the file in the link above would become fine Vim help
only with `$ pandoc -w plain ToggleKeymap.txt` if only I
change headers like `:SetKeymap` into `\*:SetKeymap\*`,
but 2. and/or 4. might still be desirable.

/bpj

--
--
You received this message from the "vim_use" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php

---
You received this message because you are subscribed to the Google Groups "vim_use" group.
To unsubscribe from this group and stop receiving emails from it, send an email to vim_use+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

No comments:

Post a Comment