Writing Help Files: Guidelines for Formatting and Tagging

different encoding for help files of the same language but in a different directory. Hints for translators: - Do not translate the tags. This makes it possible to use 'helplang' to specify the preferred language. You may add new tags in your language. - When you do not translate a part of a file, add tags to the English version, using the "tag@en" notation. - Make a package with all the files and the tags file available for download. Users can drop it in one of the "doc" directories and start use it. Report to the development team, so they can add a link on www.vim.org. - Use the |:helptags| command to generate the tags files. It will find all languages in the specified directory. ============================================================================== 3. Writing help files *help-writing* For ease of use, a Vim help file for a plugin should follow the format of the standard Vim help files, except for the first line. If you are writing a new help file it's best to copy one of the existing files and use it as a template. The first line in a help file should have the following format: > *plugin_name.txt* {short description of the plugin} The first field is a help tag where ":help plugin_name" will jump to. The remainder of the line, after a Tab, describes the plugin purpose in a short way. This will show up in the "LOCAL ADDITIONS" section of the main help file. Check there that it shows up properly: |local-additions|. If you want to add a version number or last modification date, put it in the second line, right aligned. At the bottom of the help file, place a Vim modeline to set the 'textwidth' and 'tabstop' options and the 'filetype' to "help". Never set a global option in such a modeline, that can have undesired consequences. TAGS To define a help tag, place the name between asterisks ("*tag-name*"). The tag-name should be different from all the Vim help tag names and ideally should begin with the name of the Vim plugin. The tag name is usually right aligned on a line. When referring to an existing help tag and to create a hot-link,

This section provides guidelines for writing help files for Vim plugins, emphasizing the importance of following the standard Vim help file format. It details the required format for the first line, including the plugin name and a short description. It covers defining help tags with asterisks, ensuring they are unique and ideally begin with the plugin name. It also explains how to create hot-links to existing help tags using the |tag| notation.