.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 .\" ======================================================================== .\" .IX Title "Locale::Po4a::Sgml 3pm" .TH Locale::Po4a::Sgml 3pm "2020-08-19" "Po4a Tools" "Po4a Tools" .\" 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::Sgml \- convert SGML documents from/to PO files .SH "DESCRIPTION" .IX Header "DESCRIPTION" The po4a (\s-1PO\s0 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 Locale::Po4a::Sgml is a module to help the translation of documentation in the \s-1SGML\s0 format into other [human] languages. .PP This module uses \fBonsgmls\fR(1) to parse the \s-1SGML\s0 files. Make sure it is installed. Also make sure that the \s-1DTD\s0 of the \s-1SGML\s0 files are installed in the system. .SH "OPTIONS ACCEPTED BY THIS MODULE" .IX Header "OPTIONS ACCEPTED BY THIS MODULE" .IP "\fBdebug\fR" 4 .IX Item "debug" Space separated list of keywords indicating which part you want to debug. Possible values are: tag, generic, entities and refs. .IP "\fBverbose\fR" 4 .IX Item "verbose" Give more information about what's going on. .IP "\fBtranslate\fR" 4 .IX Item "translate" Space separated list of extra tags (beside the \s-1DTD\s0 provided ones) whose content should form an extra msgid. .IP "\fBsection\fR" 4 .IX Item "section" Space separated list of extra tags (beside the \s-1DTD\s0 provided ones) containing other tags, some of them being of category \fBtranslate\fR. .IP "\fBindent\fR" 4 .IX Item "indent" Space separated list of tags which increase the indentation level. .IP "\fBverbatim\fR" 4 .IX Item "verbatim" The layout within those tags should not be changed. The paragraph won't get wrapped, and no extra indentation space or new line will be added for cosmetic purpose. .IP "\fBempty\fR" 4 .IX Item "empty" Tags not needing to be closed. .IP "\fBignore\fR" 4 .IX Item "ignore" Tags ignored and considered as plain char data by po4a. That is to say that they can be part of an msgid. For example, is a good candidate for this category since putting it in the translate section would create msgids not being whole sentences, which is bad. .IP "\fBattributes\fR" 4 .IX Item "attributes" A space separated list of attributes that need to be translated. You can specify the attributes by their name (for example, \*(L"lang\*(R"), but you can also prefix it with a tag hierarchy, to specify that this attribute will only be translated when it is into the specified tag. For example: lang specifies that the lang attribute will only be translated if it is in an tag, which is in a tag. The tag names are actually regular expressions so you can also write things like lang to only translate lang attributes that are in an or a tag. .IP "\fBqualify\fR" 4 .IX Item "qualify" A space separated list of attributes for which the translation must be qualified by the attribute name. Note that this setting automatically adds the given attribute into the 'attributes' list too. .IP "\fBforce\fR" 4 .IX Item "force" Proceed even if the \s-1DTD\s0 is unknown or if onsgmls finds errors in the input file. .IP "\fBinclude-all\fR" 4 .IX Item "include-all" By default, msgids containing only one entity (like '&version;') are skipped for the translator comfort. Activating this option prevents this optimisation. It can be useful if the document contains a construction like \&\*(L"Á\*(R", even if I doubt such things to ever happen... .IP "\fBignore-inclusion\fR" 4 .IX Item "ignore-inclusion" Space separated list of entities that won't be inlined. Use this option with caution: it may cause onsgmls (used internally) to add tags and render the output document invalid. .SH "STATUS OF THIS MODULE" .IX Header "STATUS OF THIS MODULE" The result is perfect. I.e., the generated documents are exactly the same. But there are still some problems: .IP "\(bu" 2 The error output of onsgmls is redirected to /dev/null by default, which is clearly bad. I don't know how to avoid that. .Sp The problem is that I have to \*(L"protect\*(R" the conditional inclusions (i.e. the \&\f(CW\*(C`\*(C'\fR stuff) from onsgmls. Otherwise onsgmls eats them, and I don't know how to restore them in the final document. To prevent that, I rewrite them to \f(CW\*(C`{PO4A\-beg\-foo}\*(C'\fR and \&\f(CW\*(C`{PO4A\-end}\*(C'\fR. .Sp The problem with this is that the \f(CW\*(C`{PO4A\-end}\*(C'\fR and such I add are invalid in the document (not in a

tag or so). .Sp If you want to view the onsgmls output, just add the following to your command line (or po4a configuration line): .Sp .Vb 1 \& \-o debug=onsgmls .Ve .IP "\(bu" 2 It does work only with the DebianDoc and DocBook \s-1DTD.\s0 Adding support for a new \s-1DTD\s0 should be very easy. The mechanism is the same for every \s-1DTD,\s0 you just have to give a list of the existing tags and some of their characteristics. .Sp I agree, this needs some more documentation, but it is still considered as beta, and I hate to document stuff which may/will change. .IP "\(bu" 2 Warning, support for DTDs is quite experimental. I did not read any reference manual to find the definition of every tag. I did add tag definition to the module 'till it works for some documents I found on the net. If your document use more tags than mine, it won't work. But as I said above, fixing that should be quite easy. .Sp I did test DocBook against the \s-1SAG\s0 (System Administrator Guide) only, but this document is quite big, and should use most of the DocBook specificities. .Sp For DebianDoc, I tested some of the manuals from the \s-1DDP,\s0 but not all yet. .IP "\(bu" 2 In case of file inclusion, string reference of messages in \s-1PO\s0 files (i.e. lines like \f(CW\*(C`#: en/titletoc.sgml:9460\*(C'\fR) will be wrong. .Sp This is because I preprocess the file to protect the conditional inclusion (i.e. the \f(CW\*(C`\*(C'\fR stuff) and some entities (like &version;) from onsgmls because I want them verbatim to the generated document. For that, I make a temp copy of the input file and do all the changes I want to this before passing it to onsgmls for parsing. .Sp So that it works, I replace the entities asking for a file inclusion by the content of the given file (so that I can protect what needs to be in a subfile also). But nothing is done so far to correct the references (i.e., filename and line number) afterward. I'm not sure what the best thing to do is. .SH "AUTHORS" .IX Header "AUTHORS" This module is an adapted version of sgmlspl (\s-1SGML\s0 postprocessor for the \&\s-1ONSGMLS\s0 parser) which was: .PP .Vb 1 \& Copyright © 1995 David Megginson .Ve .PP The adaptation for po4a was done by: .PP .Vb 2 \& Denis Barbier \& Martin Quinson (mquinson#debian.org) .Ve .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" .Vb 2 \& Copyright © 1995 David Megginson . \& Copyright © 2002\-2005 SPI, Inc. .Ve .PP This program is free software; you may redistribute it and/or modify it under the terms of \s-1GPL\s0 (see the \s-1COPYING\s0 file).