Mercurial > babel > old > babel-test

annotate doc/setup.txt @ 77:5c819411e4af

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated frontend screens for added sorting features.
author cmlenz
date Fri, 08 Jun 2007 23:27:35 +0000
parents 84d400066b71
children ee043bb666f0
rev   line source
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
3 ================================
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
4 Distutils/Setuptools Integration
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
5 ================================
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
6
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
7 Babel provides commands for integration into ``setup.py`` scripts, based on
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
8 either the ``distutils`` package that is part of the Python standard library,
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
9 or the third-party ``setuptools`` package.
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
10
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
11 These commands are available by default when Babel has been properly installed,
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
12 and ``setup.py`` is using ``setuptools``. For projects that use plain old
40
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
13 ``distutils``, the commands need to be registered explicitly, for example:
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
14
4525549aa6cc Syntax highlighting for the docs.
cmlenz
parents: 2
diff changeset
15 .. code-block:: python
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
16
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
17 from distutils.core import setup
54
b3395b285104 Rename the `babel.catalog` package to `babel.messages` for consistency with the other package names.
cmlenz
parents: 51
diff changeset
18 from babel.messages import frontend as babel
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
19
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
20 setup(
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
21 ...
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
22 cmd_class = {'extract_messages': babel.extract_messages}
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
23 )
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
24
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
25
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
26 .. contents:: Contents
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
27 :depth: 2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
28 .. sectnum::
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
29
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
30
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
31 extract_messages
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
32 ================
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
33
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
34 The ``extract_messages`` command is comparabe to the GNU ``xgettext`` program:
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
35 it can extract localizable messages from a variety of difference source files,
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
36 and generate a PO (portable object) template file from the collected messages.
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
37
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
38 If the command has been correctly installed or registered, another project's
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
39 ``setup.py`` script should allow you to use the command::
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
40
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
41 $ ./setup.py extract_messages --help
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
42 Global options:
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
43 --verbose (-v) run verbosely (default)
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
44 --quiet (-q) run quietly (turns verbosity off)
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
45 --dry-run (-n) don't actually do anything
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
46 --help (-h) show detailed help message
77
5c819411e4af Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
47
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
48 Options for 'extract_messages' command:
49
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
49 --charset charset to use in the output file
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
50 --keywords (-k) space-separated list of keywords to look for in
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
51 addition to the defaults
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
52 --no-default-keywords do not include the default keywords
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
53 --mapping-file (-F) path to the mapping configuration file
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
54 --no-location do not include location comments with filename and
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
55 line number
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
56 --omit-header do not include msgid "" entry in header
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
57 --output-file (-o) name of the output file
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
58 --width (-w) set output line width (default 76)
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
59 --no-wrap do not break long message lines, longer than the
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
60 output line width, into several lines
77
5c819411e4af Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
61 --sort-output generate sorted output (default False)
5c819411e4af Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
62 --sort-by-file sort output by file location (default False)
62
84d400066b71 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 54
diff changeset
63 --input-dirs directories that should be scanned for messages
77
5c819411e4af Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
64
5c819411e4af Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
65 usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
5c819411e4af Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
66 or: setup.py --help [cmd1 cmd2 ...]
5c819411e4af Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
67 or: setup.py --help-commands
5c819411e4af Updated frontend screens for added sorting features.
cmlenz
parents: 62
diff changeset
68 or: setup.py cmd --help
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
69
51
7f61453c1bea Fixed a bug regarding plural msgid's handling when writing the `.pot` file.
palgarvio
parents: 49
diff changeset
70 Running the command will produce a PO template file::
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
71
49
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
72 $ ./setup.py extract_messages --output-file foobar/locale/messages.pot
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
73 running extract_messages
49
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
74 extracting messages from foobar/__init__.py
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
75 extracting messages from foobar/core.py
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
76 ...
51
7f61453c1bea Fixed a bug regarding plural msgid's handling when writing the `.pot` file.
palgarvio
parents: 49
diff changeset
77 writing PO template file to foobar/locale/messages.pot
49
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
78
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
79
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
80 Method Mapping
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
81 --------------
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
82
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
83 The mapping of file patterns to extraction methods (and options) can be
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
84 specified using a configuration file that is pointed to using the
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
85 ``--mapping-file`` option shown above. Alternatively, you can configure the
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
86 mapping directly in ``setup.py`` using a keyword argument to the ``setup()``
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
87 function:
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
88
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
89 .. code-block:: python
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
90
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
91 setup(...
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
92
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
93 message_extractors = {
62
84d400066b71 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 54
diff changeset
94 'foobar': [
84d400066b71 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 54
diff changeset
95 ('**.py', ('python', None),
84d400066b71 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 54
diff changeset
96 ('**/templates/**.html', ('genshi', None),
84d400066b71 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 54
diff changeset
97 ('**/templates/**.txt', ('genshi', {
84d400066b71 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 54
diff changeset
98 'template_class': 'genshi.template.text.TextTemplate'
84d400066b71 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 54
diff changeset
99 })
84d400066b71 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 54
diff changeset
100 ],
49
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
101 },
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
102
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
103 ...
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
104 )
2
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
105
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
106
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
107 Options
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
108 -------
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
109
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
110 As shown in the ``--help`` output above, the ``extract_messages`` command
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
111 accepts the following options:
b2492365f186 Forgot to check in the doc directory.
cmlenz
parents:
diff changeset
112
49
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
113 +-----------------------------+----------------------------------------------+
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
114 | Option | Description |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
115 +=============================+==============================================+
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
116 | ``--charset`` | charset to use in the output file |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
117 +-----------------------------+----------------------------------------------+
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
118 | ``--keywords`` (``-k``) | space-separated list of keywords to look for |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
119 | | in addition to the defaults |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
120 +-----------------------------+----------------------------------------------+
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
121 | ``--no-default-keywords`` | do not include the default keywords |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
122 +-----------------------------+----------------------------------------------+
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
123 | ``--mapping-file`` (``-F``) | path to the mapping configuration file |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
124 +-----------------------------+----------------------------------------------+
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
125 | ``--no-location`` | do not include location comments with |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
126 | | filename and line number |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
127 +-----------------------------+----------------------------------------------+
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
128 | ``--omit-header`` | do not include msgid "" entry in header |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
129 +-----------------------------+----------------------------------------------+
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
130 | ``--output-file`` (``-o``) | name of the output file |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
131 +-----------------------------+----------------------------------------------+
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
132 | ``--width`` (``-w``) | set output line width (default 76) |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
133 +-----------------------------+----------------------------------------------+
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
134 | ``--no-wrap`` | do not break long message lines, longer than |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
135 | | the output line width, into several lines |
daf35e2ad044 Support a `message_extractors` keyword argument directly in `setup()`. Closes #4.
cmlenz
parents: 40
diff changeset
136 +-----------------------------+----------------------------------------------+
62
84d400066b71 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 54
diff changeset
137 | ``--input-dirs`` | directories that should be scanned for |
84d400066b71 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 54
diff changeset
138 | | messages |
84d400066b71 The order of extraction methods is now preserved (see #10).
cmlenz
parents: 54
diff changeset
139 +-----------------------------+----------------------------------------------+
Copyright (C) 2012-2017 Edgewall Software