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

How plugin writers write help document?

Expand Messages
  • othree
    Hi All I have maintain several plugins. But some of them don t have Vim style document. I am wondering is there any support tool for write vim document. Or is
    Message 1 of 6 , Sep 1, 2013
      Hi All

      I have maintain several plugins.

      But some of them don't have Vim style document.
      I am wondering is there any support tool for write vim document.
      Or is there any good practice while writing Vim style document.


      Thanks.

      --
      --
      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@....
      For more options, visit https://groups.google.com/groups/opt_out.
    • Tony Mechelynck
      ... Any script to be used with Vim (global plugin, filetype plugin, syntax script, indent script, etc.) may (and IMHO should) have its own documentation. Vim
      Message 2 of 6 , Sep 1, 2013
        On 01/09/13 14:39, othree wrote:
        > Hi All
        >
        > I have maintain several plugins.
        >
        > But some of them don't have Vim style document.
        > I am wondering is there any support tool for write vim document.
        > Or is there any good practice while writing Vim style document.
        >
        >
        > Thanks.
        >

        Any script to be used with Vim (global plugin, filetype plugin, syntax
        script, indent script, etc.) may (and IMHO should) have its own
        documentation. Vim can be used to write the help.

        A very short "help about writing help" is at ":help write-local-help"
        (without quotes of course). There are things it doesn't explain: for
        instance, "blue" (example) text starts (IIUC) at the first nonempty line
        following a line ending in the character > and ends at the line
        preceding the first empty line or line starting with < (whichever comes
        first) after that. These > and < markers themselves are usually
        highlighted as "invisible" (unless a non-default colorscheme makes them
        visible).

        To find about "good help writing practices" you should complement
        reading the above-mentioned paragraph (which IMHO is a must) bu looking
        at how the helpfiles distributed with Vim and with the third-party
        plugins which have them are written.


        Best regards,
        Tony.
        --
        I always will remember -- I was in no mood to trifle;
        'Twas a year ago November -- I got down my trusty rifle
        I went out to shoot some deer And went out to stalk my prey --
        On a morning bright and clear. What a haul I made that day!
        I went and shot the maximum I tied them to my bumper and
        The game laws would allow: I drove them home somehow,
        Two game wardens, seven hunters, Two game wardens, seven hunters,
        And a cow. And a cow.

        The Law was very firm, it People ask me how I do it
        Took away my permit-- And I say, "There's nothin' to it!
        The worst punishment I ever endured. You just stand there lookin' cute,
        It turns out there was a reason: And when something moves, you shoot."
        Cows were out of season, and And there's ten stuffed heads
        One of the hunters wasn't insured. In my trophy room right now:
        Two game wardens, seven hunters,
        And a pure-bred guernsey cow.
        -- Tom Lehrer, "The Hunting Song"

        --
        --
        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@....
        For more options, visit https://groups.google.com/groups/opt_out.
      • Marc Weber
        Today you should - write a doc/*.txt file (for vim s internal help command and browser) - a README(.rst/.rd) document for github - install/ usage instructions
        Message 3 of 6 , Sep 2, 2013
          Today you should
          - write a doc/*.txt file (for vim's internal help command and browser)
          - a README(.rst/.rd) document for github
          - install/ usage instructions for www.vim.org site (if you choose to
          upload your plugin)

          Yes - this means duplication. And yes, I would have liked to improve
          this for a long time, but never had time to actually do so :(

          About doc/*.txt files: What is important to the user?
          use links and references and make appearance close to what others do.
          Eg look at :h.

          Marc Weber

          --
          --
          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@....
          For more options, visit https://groups.google.com/groups/opt_out.
        • Nikolay Pavlov
          ... You are a programmer! You should: - For each plugin write doc/*.txt. Write README contents and installation instructions somewhere here (I write README in
          Message 4 of 6 , Sep 2, 2013


            On Sep 2, 2013 2:04 PM, "Marc Weber" <marco-oweber@...> wrote:
            >
            > Today you should
            > - write a doc/*.txt file (for vim's internal help command and browser)
            > - a README(.rst/.rd) document for github
            > - install/ usage instructions for www.vim.org site (if you choose to
            >   upload your plugin)

            You are a programmer! You should:

            - For each plugin write doc/*.txt. Write README contents and installation instructions somewhere here (I write README in the intro section: typically the first one; installation instructions are same for all plugins).
            - Write *once* a script that will transform intro section into README and vim.org description. It may also contain installation instructions for all plugins since they are the same. Mine is here: sourceforge.net/p/vimpluginloader/dev-tools/ci/default/tree/pkgdo.pl.

            > Yes - this means duplication. And yes, I would have liked to improve
            > this for a long time, but never had time to actually do so :(
            >
            > About doc/*.txt files: What is important to the user?
            > use links and references and make appearance close to what others do.
            > Eg look at :h.
            >
            > Marc Weber
            >
            > --
            > --
            > 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@....
            > For more options, visit https://groups.google.com/groups/opt_out.

            --
            --
            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@....
            For more options, visit https://groups.google.com/groups/opt_out.
          • Marc Weber
            ... But my time is limited, too. I know what I should: - write scripts uploading to www.vim.org - to github - write a new documentation system (or use an
            Message 5 of 6 , Sep 2, 2013
              Excerpts from Nikolay Pavlov's message of Mon Sep 02 12:20:28 +0200 2013:
              > You are a programmer! You should:
              But my time is limited, too.

              I know what I should:
              - write scripts uploading to www.vim.org
              - to github
              - write a new documentation system (or use an existing one)
              which converts my docs to what I wrote earlier.

              But even then it would be "me" only using it.
              And uploading to github and www.vim.org would still be redundant.

              Yes - I'd like to have people register a github url only and be done.

              The problem is that sourceforge's hosting might not be the best fit to
              get this done because you eventuall also want new features such as
              - code search
              - online code browsing
              - ..
              and Bram did not reply to a request asking whether we may look for a
              different sponsoring.

              I personally cannot guarantee being able to pay for hosting for the next
              10 years.

              Pay me and this all will be done in 2 weeks or less :-P

              You can find my attempt to get started with some ideas here:
              http://titanpad.com/AcUfZQjXUz
              Garbas even started an implementation that time - I nevre had time to
              review it.

              If somebody wants to pickup and join you're welcome.

              Marc Weber

              --
              --
              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@....
              For more options, visit https://groups.google.com/groups/opt_out.
            • lith
              ... It s not necessarily good practice but I wrote a ruby script[1] that takes a template file (which usually contains some sort of Getting started section)
              Message 6 of 6 , Sep 2, 2013
                > But some of them don't have Vim style document.
                > I am wondering is there any support tool for write vim document.
                > Or is there any good practice while writing Vim style document.

                It's not necessarily good practice but I wrote a ruby script[1] that takes a template file (which usually contains some sort of "Getting started" section) and a file list and then extracts comments from a plugin's vim source files and creates a help file for you. IMHO it's easier to keep the help file up to date this way.

                [1]
                https://github.com/tomtom/vimtlib/blob/master/ruby/vimdedoc.rb

                --
                --
                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@....
                For more options, visit https://groups.google.com/groups/opt_out.
              Your message has been successfully submitted and would be delivered to recipients shortly.