Loading ...
Sorry, an error occurred while loading the content.

Re: Formatting help files

Expand Messages
  • Pablo Giménez
    El 28 de mayo de 2010 19:03, Tony Mechelynck ... Thanks Tony. I am already following these rules to format my help files. But txtfmt plugin is really useful
    Message 1 of 32 , Jun 1, 2010
    • 0 Attachment
      El 28 de mayo de 2010 19:03, Tony Mechelynck <antoine.mechelynck@...> escribió:
      On 28/05/10 12:48, Pablo Giménez wrote:
      Hi.
      I have some help files along with my scripts and I wanto give them a
      better formatting.
      So far the text layout is not too  bad, but I am wondering is there is
      anyway to make some letter to appear as bold or italic, like when you
      write a wiki.
      Is this possible with vim help files format????
      thanks

      --
      Un saludo
      Best Regards
      Pablo Giménez

      If these help files are to be used by other Vim users (e.g. because you distribute them with one or more Vim scripts), then you should stick to "standard" help formatting. In that case you cannot make sure that any particular text will be in any _particular_ color, boldness, etc., because any user may have a different "preferred colorscheme", and colorschemes are allowed to set any coloring scheme. But you can make some parts of the text appear in a different color than the rest to any user who has set ":syntax on", by following the same rules as in the help files distributed with Vim, as follows:
      Thanks  Tony.
      I am already following these rules to format my help files.
      But txtfmt plugin is really useful to make a more professional look to it.
      So probably I will add this pluging along side with my one, which basically a compilation of plugins and scripts to offer a better help.

      * Always put a modeline at the bottom, as Bram does with Vim's helpfiles. Never set a global option in such a modeline, that can have consequences undesired by whoever reads that help.

      * Where you define a help tag, put its *help-tag-name* between asterisks. Then after the user runs |:helptags| or |:UseVimball| he will be able to use ":help help-tag-name" to go to it. The name should be distinctive and different from all help tags already used by Vim; ideally it should begin with the name of your plugin.

      * To hotlink to an 'option', just put its name between single quotes, Vim is clever enough to highlight that the right way.

      * To hotlink to a |help-tag-name| for something other than an option, put it between |bars| (q.v.)

      * The words "Note" and "TODO" automagically receive distinctive highlighting.

      * See also (e.g. by looking at some of the Vim helpfiles after setting ":syntax off", or by viewing them in some dumb editor such as Notepad) how the Vim help uses some character at the start or end of some lines to produce distintive highlighting. For instance the following have a meaning (I'm not sure I found them all):

             - a special key name expressed either in <> notation as in <PageDown>, or as a Ctrl character as in CTRL-X
             - anything between {braces}, e.g. {lhs} and {rhs}
             - a greater-than sign at the end of the line (maning: here comes a block of ex-commands)
             - a less-than sign as the first nonblank on a line (meaning: the line above was the last one of a block of ex-commands)
             - a line starting in column 1 also implicitly stops any block of ex-commands before it.
             - a tilde at the end of a line (to give this line a different colour, usually for a column heading)


      Best regards,
      Tony.
      --
      ARTHUR:  Bloody peasant!
      DENNIS:  Oh, what a give away.  Did you hear that, did you hear that, eh?
              That's what I'm on about -- did you see him repressing me, you saw it
              didn't you?
                                       The Quest for the Holy Grail (Monty Python)



      --
      Un saludo
      Best Regards
      Pablo Giménez

      --
      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
    • Brett Stahlman
      ... No problem. Glad to hear it works for you. Looks like you ve come up with a good approach. Let me know if you have any other issues... Sincerely, Brett
      Message 32 of 32 , Jun 9, 2010
      • 0 Attachment
        On Jun 8, 9:33 am, Pablo Giménez <pablog...@...> wrote:
        > Perfecto working liek a  charm.
        > Thanks
        > I have put this in my after/ftplugin/txtfmt.vim
        >
        > " Disable txtfmt formating if we aren't in gui mode
        > if !has("gui_running")
        >     call tdvim#StripTxtfmtTokens("help")
        > endif
        >
        > " Enable refresh if coor scheme changes:
        > autocmd ColorScheme <buffer> :Refresh
        >
        > Which seems to work nice.
        > Thansk for your help!

        No problem. Glad to hear it works for you. Looks like you've come up
        with a good approach. Let me know if you have any other issues...

        Sincerely,
        Brett Stahlman

        ...[snip]...

        --
        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
      Your message has been successfully submitted and would be delivered to recipients shortly.