Re: man pages for Subversion

On 14 aug 2013, at 20:47, Mattias Engdegård <mattiase_at_bredband.net> wrote:

> 12 aug 2013 kl. 12.38 skrev Julian Foad:
>
>> Hi James. I have one thing to throw into the mix, which you might be interested in looking at. I experimented a few months ago with generating both the C help strings and man pages from an XML source file. My patch to do this is attached; it is complete and and usable, although not finished or quite how I would want it.
>
> How about including the marked-up source in the svn binary (as C constant strings) and do the rendering at run time, when the user does "svn help"? Otherwise, it would be tricky to handle translations properly - the translator must work on the marked-up text and it should be possible to try out new translations without rebuilding the binaries.

Is that possible today?

> This has the extra benefit of allowing the help text to be rendered to the width of the terminal and to (optionally) use terminal effects such as bold and underline.

Given the verbosity of some help texts I definitely think the source format should not care about terminal width. It must be a major pain to translate given the line breaks? Whether the line breaks are introduced during runtime or build matters less, but the later the better.

> The original could either live in a separate file, as in your patch, or as actual C constants. In any case, it probably makes things a lot easier for the translators if the text appears as strings in the same subversion.pot as everything else.
>
> (Personally I would prefer something more light-weight than XML, but perhaps it would give you an excuse to allow the --xml flag with svn help.)

Many recently developed software frameworks define their strings in XML because:
a) translation processes are well defined for XML, in a larger perspective since almost all documentation is done in XML (ok, not a great driver in this project except keeping svnbook up to date)
b) XML is so easy to transform into multiple distribution formats.

I know there is a lot of resistance toward the heavy-weight XML, but authoring is actually where XML excels (as opposed to data interchange where lighter formats can be preferred).

Cheers,
Thomas Ã….
Received on 2013-08-14 23:42:39 CEST