LOCALE::PO4A::VIMHELP.3PM(1)

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.

SEE ALSO
Locale::Po4a::TransTractor(3pm), po4a(7)

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).