[Po4a-devel][RFC] Multi-lines verbatim blocks

[Nicolas François]

On Tue, Nov 16, 2004 at 01:43:35PM +0100, martin.quinson@imag.fr wrote:
> On Mon, Nov 15, 2004 at 11:55:31PM +0100, Nicolas François wrote:
> > Hello,
> > 
> > To solve an issue with the man module, I've implemented a way to spec=
ify
> > some (multi-lines) verbatim blocks.
> 
> I'm not sure I understand what you're talking about. Could you please g=
ive
> an example of use? Why can't you simply pushline all the lines until yo=
u
> encounter the end block boundary? 

Here is what most tetex-bin manpages contain:
(it is not always exactly the same header, I'm using amstex as an example)
.\"=====================================================================
.if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
.if n .ds TX TeX
.ie t .ds OX \fIT\v'+0.25m'E\v'-0.25m'X\fP\" for troff
.el .ds OX TeX\" for nroff
.\" the same but obliqued
.\" BX definition must follow TX so BX can use TX
.if t .ds BX \fRB\s-2IB\s0\fP\*(TX
.if n .ds BX BibTeX
.\" LX definition must follow TX so LX can use TX
.if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
.if n .ds LX LaTeX
.if t .ds AX \fRA\\h'-0.1667m'\\v'0.20v'M\\v'-0.20v'\\h'-0.125m'S\fP\*(TX
.if n .ds AX AmSTeX
.if t .ds AY \fRA\\h'-0.1667m'\\v'0.20v'M\\v'-0.20v'\\h'-0.125m'S\fP\*(LX
.if n .ds AY AmSLaTeX
.\"=====================================================================

This permits to define nice formating for TeX, LaTeX, etc. if the document
is processed in troff mode (it only works with some devices, like ps) and
fall back to a simple representation in nroff mode.
These strings are later used as "\*(TX", "\*(NX", etc.

I wanted to indicate to po4a that when this sequence of lines is
encountered, they only have to be copied in the translation as is, without
trying to parse them.
(Note that finally I decided to split this block in smaller blocks for a
better reuse, because the header vary from one page to the other)


Here is another example. Some pages of the groff packages define a OP
macro, which simplify writing options:
.de OP
.ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
.el .RB "[\ " "\\$1" "\ ]"
..

(I'm not sure, but it seems to specify that depending on the number of
arguments, it uses the first or the second line; this permits to always
have the options between brackets in the roman font, the option in bold
and the argument, if any, in italic).


Here is another example with the cron-apt.sgml file (old #278365)
The user would have specified the following sequence of lines:
<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.8: manpage.sgml
        docbook-to-man $< > $@
  -->

Your fix is much better in this case. I just want to show that it could
give users a solution for some points we can't (or are not inclined to)
deal with.


I have to admit that I didn't really think about using begin and end
boundaries.

Boundaries are simpler to implement. They may be a little bit more risky
(if the end boundary is not found, all the document will be untranslated),
but it will up to the user to specify the right ones and verify the result.


> > Another Note:
> > I've not tried this, but it may solve #263298 (Please let -gettextize=
 know
> > about addendums and remove them automatically).
> 
> It's not explicitely tagged, but I tend to think that this bug is a
> "wontfix" one. The asked feature could incitate upstream maintainer to =
do
> stupidities with the translation files.

The last example using the po4a-gettextize manpage, imagine it belongs to
manpages-fr, and this page was not translated with po4a), then somebody
(lets call him Denis) would create a file containing:
.SH "TRADUCTION"
.IX Header "TRADUCTION"
.Vb 1
\& Martin Quinson <martin.quinson@tuxfamily.org>
.Ve

(it could latter be used as an addendum by adding a header). Then these
strings would not be given to the parser, they wouldn't appear in the
french po during gettextization, and the English and French POs should then
match (I still did not try it).
If needed, the addendum format could be used/supported.



I hope what I'm proposing is more clear now.

I'm still not convinced it is really useful or easy to use.

Kind Regards,
-- 
Nekral