LOCALE::PO4A::VIMHELP.3PM

Section: User Contributed Perl Documentation (1)
Updated: 2025-05-13
Index Return to Main Contents

NAME

Locale::Po4a::VimHelp - convert Vim help files from/to PO files.

DESCRIPTION

The po4a (PO for anything) project goal is to ease translations (and more interestingly, the maintenance of translations) using gettext tools on areas where they were not expected like documentation.

"Locale::Po4a::VimHelp" is a module to help the translation of Vim help file. See also Writing help files <https://vimhelp.org/helphelp.txt.html#help-writing> for its syntax.

STATUS OF THIS MODULE

This module is in an early stage of development. It has been successfully tested on simple files like "helphelp.txt". However, it has not yet been tested on full help files, and the way it parses them may change for fixes and improvements, especially paragraph wrapping.

DEVELOPING

Parsing Vim help files for po4a is difficult. Here are some obstacles while developing this module. If you have a better idea, feel free to suggest a patch (with additional test cases).

"1. foo" sounds like an ordered list

Not necessarily. Consider the following paragraph.

 There are 2 wandering tanukis, not
 1. He's using his cloning technique.

For the same reason, what appears to be a heading (e.g. "1.1 bar") or an unordered list (e.g. "o baz") cannot be detected.

Flushed right tags should be excluded from translation target

This topic is also difficult since it relates to language differences in localization.

Consider the following example.

 Such a common and short concept in some languages *tags*

which might be translated to

 They are unfamiliar, there are no corresponding concepts and *tags*
 it takes a longer sentence to express them in this language

When this happens, you have to decide at what point you want to add a tag nicely. This shouldn't be easy. The Vim help file is in a hard wrapped format, even for parts that are not code blocks.

The same applies to tag references such as "|ref|".

Leveraging "--wrapcol" to monitor text widths

Using the "--wrapcol" option to issue warnings when text width exceeds specified limits seems like a reasonable approach. The official Vim help files feature a mode line, such as "vim:tw=78:ts=8:noet:ft=help:norl:", as seen in "runtime/doc/if_perl.txt" <https://github.com/vim/vim/blob/04cc8975930b7b2c5d6753d3eddf57dab2816518/runtime/doc/if_perl.txt#L307>. However, there are a few challenges to consider:

File Parsing Behavior: If this option is implemented, it would be ideal to read the entire file first, detect whether the mode line exists, and determine which sections are affected. Unfortunately, the progressive parsing mechanism is not employed in this case.
Default vs. Custom Values: The generic default value of "--wrapcol" is 76, whereas Vim help files commonly use 78. In most cases, the value in the options passed to this module defaults to 76, but it is unclear whether this value was explicitly set or implicitly applied.

AUTHORS

 gemmaro <gemmaro.dev@gmail.com>

COPYRIGHT AND LICENSE

 Copyright © 2024, 2025 gemmaro.

This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file).

This document was created by using the manual pages.
Time: 22:04:19 GMT, May 13, 2025