Re: [PATCH] better docs in gettext.texi and xgettext.texi

[Miguel Ángel Arruga Vivas]

Hi Andrea,

CC also Bruno as writer of the "FIXME" comment.

"Andrea G. Monaco" <andrea.monaco@autistici.org> writes:

> a couple weeks ago I sent a patch to the docs. Does anyone have some
> feedback?

Thanks for your patch, and sorry for the delay; I've answered your
previous email but I took too much for these other two.

I have some comments inline, but I'd like you don't take any negative
view to some of the changes as a discouragement but only as my humble
opinion---I might be wrong too.

As a general comment, I'd like to say that usually a change should have
one and only one objective, either to provide an enhancement or to fix
an error, and be complete by itself, but I feel some of the changes have
a different objective (style changes) than others (example addition),
which should be different commits/patches.

> -right away?  The answer is: for historical reasons.  When @code{xgettext}
> +right away?  For historical reasons.  When @code{xgettext}

From my POV, this change doesn't enhance the text too much.

>  was specified, the distinction between a PO file and PO file template
> -was fuzzy, and the suffix @samp{.pot} wasn't in use at that time.)
> +was fuzzy, and the suffix @samp{.pot} wasn't in use.)

I don't think this is an enhancement neither, sorry.

> +Here's an example invocation of @code{xgettext}:
> +@example
> +xgettext --keyword=_ --from-code=utf-8 *.c *.h
> +@endexample
> +This creates a @file{messages.po} file with all translatable strings
> +found in @samp{.c} and @samp{.h} files in the current directory.
> +The @code{--keyword} option specifies @code{_} as an additional keyword for
> +@code{gettext} calls; you must use this argument if you declared @code{_} as
> +a macro for @code{gettext}. Also the @code{--from-code} option specifies
> +encoding of the input files; you need it if your translatable strings
> +contain non-ASCII characters.

I'm not sure about this paragraph: the underscore macro is already
explained on Mark Keywords section.  I've taken some inspiration, but
I've glued with the old paragraph on my proposed patch.  I personally
don't like the "you must/need" approach either, as I don't find it very
instructive.  The documentation of each option is provided afterwards,
an example should give a context with the specific needs and show how to
perform the operation there; the reader must extrapolate to their case
and needs with the full documentation at hand.

> -xgettext [@var{option}] [@var{inputfile}] @dots{}
> +xgettext [@var{option}] @dots{} [@var{inputfile}] @dots{}

This is the same convention as used on msgcat and xgettext --help
header, a change here should be uniform regarding tools and
documentation.

>  The @code{xgettext} program extracts translatable strings from given
> -input files.
> +input file(s) and generates an output PO file.

This message is mostly the xgettext --help header too.  A minor nitpick
too: it generates an output PO template file.

> -@subsection Input file location
> +@subsection Input files location
> [...]
> -Input files.
> +Input file(s).

This is the same convention as other tools like msgcat use too.

>  @item --force-po
>  @opindex --force-po@r{, @code{xgettext} option}
> -Always write an output file even if no message is defined.
> +Always write an output file even if no translatable string is found.

Message is the technical term used through the whole manual.

Best regards,
Miguel

0001-doc-Add-extra-documentation-for-xgettext.patch
Description: xgettext-intro.patch

signature.asc
Description: PGP signature