Open Stack

Hi Robert,

On 12/6/16 3:34 AM, Robert Simai wrote:
> Hi Brian,
> 
> On Monday 05 December 2016, 09:42:21 Brian Rosmaita 
> <rosmaita.fossdev at gmail.com> wrote:
>> Several projects recently enhanced the help text for configuration
>> options.  In Glance, this has resulted in strings like [0] (and there
>> are lots of other examples in that file).
>>
>> For those strings, the exact formatting isn't essential, but the
>> paragraphing and bulleted lists are important.
> 
> I see and agree, this text will lose meaning without the format.
>  
>> My question is whether having this text in a single block of
>> triple-quotes (as it is now) is useful to translators (so you can see
>> the entire context), or whether there's a way you'd prefer it to be
>> broken up so that it works better with Zanata.
> 
> Looked up your example in Zanata and must say find it horrible to translate. 
> But interestingly, Zanata at least allows to save the translation with just 
> "warnings" (not errors), if the amount of lines doesn't match. I've seen 
> this as real "errors" in other projects where you can only save as "fuzzy".
> 
> However, looking at the text and its purpose, this is not for any GUI but 
> console output and I guess that's why you limit line length to less than 72 
> characters, don't you? That would be a convention to clarify with the 
> translators but isn't easy to achieve with the Zanata UI (it uses 
> proportional fonts and has no counter). If the translator accidentally makes 
> it 80+ characters it may easily kill the formatting.

Here's the situation.  We're using oslo.config to define configuration
options and generate sample config files.  We've decided to put the help
text at the point where the option is defined so that there will be a
single place where the text is maintained.  So those strings are
actually documentation ... and I didn't realize until now that by
enclosing those strings in _(), we're asking you to translate
*documentation*, not log lines or error messages, which may not be what
you've signed up for.

As far as the line length goes, we just need to keep it short enough to
conform to the openstack python coding convention (79 char lines).  So
as long as the paragraphing is kept, I don't think the line length would
matter.

In any case, I guess the question now is whether these help text strings
should be marked for translation in the first place.

> I may not help to put things into perspective for the translators but I 
> finally think that the text block from your example is way too big and 
> should be broken down to (many!) strings. The translator shouldn't need to 
> take care of the amount of lines, line breaks, line lengths or leading 
> spaces. Formatting, if desired, needs to happen at another place, within the 
> application that does the output and may depend on screen details (e.g. 
> terminal width for console stuff).

The strings are actually marked up as RST (re-structured text), using a
limited set of tags.  In order to encourage developers to write good
documentation when adding config options, we're trying to keep the
requirements as simple as possible.  We could break things into a series
of strings, but we'd like to keep developers focused on writing good
content -- if the format in which you've got to write these things gets
too complicated, I'm afraid it will cause "inconveniences" on the
development side and make it more difficult to get good docs.

>> When we added all these blocks of text in Newton, we were focused on
>> making things easier for operators, and didn't realize that it would
>> cause problems for translators ... sorry about that!
> 
> Let's call it an inconvenience, not a problem ;-)
> 

Sounds good!  Let's continue the discussion to figure out how to make
this more convenient for all concerned.

cheers,
brian