.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "LOCALE::PO4A::VIMHELP.3PM 1" .TH LOCALE::PO4A::VIMHELP.3PM 1 2025-11-22 "perl v5.42.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Locale::Po4a::VimHelp \- convert Vim help files from/to PO files. .SH DESCRIPTION .IX Header "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. .PP \&\f(CW\*(C`Locale::Po4a::VimHelp\*(C'\fR is a module to help the translation of Vim help file. See also Writing help files for its syntax. .SH "STATUS OF THIS MODULE" .IX Header "STATUS OF THIS MODULE" This module is in an early stage of development. It has been successfully tested on simple files like \f(CW\*(C`helphelp.txt\*(C'\fR. 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. .SH DEVELOPING .IX Header "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). .ie n .IP """1. foo"" sounds like an ordered list" 4 .el .IP "\f(CW1. foo\fR sounds like an ordered list" 4 .IX Item "1. foo sounds like an ordered list" Not necessarily. Consider the following paragraph. .Sp .Vb 2 \& There are 2 wandering tanukis, not \& 1. He\*(Aqs using his cloning technique. .Ve .Sp For the same reason, what appears to be a heading (e.g. \f(CW\*(C`1.1 bar\*(C'\fR) or an unordered list (e.g. \f(CW\*(C`o baz\*(C'\fR) cannot be detected. .IP "Flushed right tags should be excluded from translation target" 4 .IX Item "Flushed right tags should be excluded from translation target" This topic is also difficult since it relates to language differences in localization. .Sp Consider the following example. .Sp .Vb 1 \& Such a common and short concept in some languages *tags* .Ve .Sp which might be translated to .Sp .Vb 2 \& They are unfamiliar, there are no corresponding concepts and *tags* \& it takes a longer sentence to express them in this language .Ve .Sp When this happens, you have to decide at what point you want to add a tag \fInicely\fR. This shouldn\*(Aqt be easy. The Vim help file is in a hard wrapped format, even for parts that are not code blocks. .Sp The same applies to tag references such as \f(CW\*(C`|ref|\*(C'\fR. .ie n .IP "Leveraging ""\-\-wrapcol"" to monitor text widths" 4 .el .IP "Leveraging \f(CW\-\-wrapcol\fR to monitor text widths" 4 .IX Item "Leveraging --wrapcol to monitor text widths" Using the \f(CW\*(C`\-\-wrapcol\*(C'\fR 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 \f(CW\*(C`vim:tw=78:ts=8:noet:ft=help:norl:\*(C'\fR, as seen in \&\f(CW\*(C`runtime/doc/if_perl.txt\*(C'\fR . However, there are a few challenges to consider: .RS 4 .IP "File Parsing Behavior" 4 .IX Item "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. .IP "Default vs. Custom Values" 4 .IX Item "Default vs. Custom Values" The generic default value of \f(CW\*(C`\-\-wrapcol\*(C'\fR 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. .RE .RS 4 .RE .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBLocale::Po4a::TransTractor\fR\|(3pm), \fBpo4a\fR\|(7) .SH AUTHORS .IX Header "AUTHORS" .Vb 1 \& gemmaro .Ve .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" .Vb 1 \& Copyright © 2024, 2025 gemmaro. .Ve .PP This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the \fICOPYING\fR file).