2012-11-11 04:14:42 +01:00
|
|
|
// -*- mode:doc; -*-
|
2013-02-13 13:59:02 +01:00
|
|
|
// vim: set syntax=asciidoc:
|
2012-11-11 04:14:42 +01:00
|
|
|
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
=== Gettext integration and interaction with packages
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
Many packages that support internationalization use the gettext
|
|
|
|
|
library. Dependencies for this library are fairly complicated and
|
2012-11-16 05:54:19 +01:00
|
|
|
therefore, deserve some explanation.
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2017-07-04 11:26:28 +02:00
|
|
|
The 'glibc' C library integrates a full-blown implementation of
|
|
|
|
|
'gettext', supporting translation. Native Language Support is
|
|
|
|
|
therefore built-in in 'glibc'.
|
|
|
|
|
|
|
|
|
|
On the other hand, the 'uClibc' and 'musl' C libraries only provide a
|
|
|
|
|
stub implementation of the gettext functionality, which allows to
|
|
|
|
|
compile libraries and programs using gettext functions, but without
|
|
|
|
|
providing the translation capabilities of a full-blown gettext
|
|
|
|
|
implementation. With such C libraries, if real Native Language Support
|
|
|
|
|
is necessary, it can be provided by the +libintl+ library of the
|
2014-08-16 15:47:22 +02:00
|
|
|
+gettext+ package.
|
|
|
|
|
|
2017-07-04 11:26:28 +02:00
|
|
|
Due to this, and in order to make sure that Native Language Support is
|
|
|
|
|
properly handled, packages in Buildroot that can use NLS support
|
|
|
|
|
should:
|
2014-08-16 15:47:22 +02:00
|
|
|
|
doc/manual: fixup ordered lists
With recent asiidoc versions (at least 10.2.0 is known to report that),
rendering the manual yields a few warnings related to ordered lists:
asciidoc: WARNING: customize-quick-guide.adoc: line 13: list item index: expected 2 got 1
asciidoc: WARNING: customize-quick-guide.adoc: line 15: list item index: expected 3 got 1
[...]
asciidoc: WARNING: customize-quick-guide.adoc: line 65: list item index: expected 13 got 1
asciidoc: WARNING: customize-quick-guide.adoc: line 66: list item index: expected 14 got 1
asciidoc: WARNING: adding-packages-gettext.adoc: line 30: list item index: expected 2 got 1
asciidoc: WARNING: adding-packages-gettext.adoc: line 41: list item index: expected 3 got 1
The reason is that we use the same index to tell asciidoc to
automatically number items.
However, the official way to provide an automatic index is to write no
index:
https://docs.asciidoctor.org/asciidoc/latest/lists/ordered/
[...] since the numbering is obvious, the AsciiDoc processor will
insert the numbers for you if you omit them:
[...]
If you number the ordered list explicitly, you have to manually keep
the list numerals sequential. Otherwise, you will get a warning.
So, abide by the documentation, and drop the repeating indices to
ordered lists where we want automatic numbering.
Note that there is another ordered list, in adding-packages-directory.adoc,
but it does use explicit, sequential numbering. For consistency within
the whole document, we also convert it.
To avoid extra useless churn, the indentation of the items is not
changed to match the elided indices.
Signed-off-by: Yann E. MORIN <yann.morin.1998@free.fr>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2024-02-10 22:24:55 +01:00
|
|
|
. Ensure NLS support is enabled when +BR2_SYSTEM_ENABLE_NLS=y+. This
|
2017-07-04 11:26:28 +02:00
|
|
|
is done automatically for 'autotools' packages and therefore should
|
|
|
|
|
only be done for packages using other package infrastructures.
|
|
|
|
|
|
doc/manual: fixup ordered lists
With recent asiidoc versions (at least 10.2.0 is known to report that),
rendering the manual yields a few warnings related to ordered lists:
asciidoc: WARNING: customize-quick-guide.adoc: line 13: list item index: expected 2 got 1
asciidoc: WARNING: customize-quick-guide.adoc: line 15: list item index: expected 3 got 1
[...]
asciidoc: WARNING: customize-quick-guide.adoc: line 65: list item index: expected 13 got 1
asciidoc: WARNING: customize-quick-guide.adoc: line 66: list item index: expected 14 got 1
asciidoc: WARNING: adding-packages-gettext.adoc: line 30: list item index: expected 2 got 1
asciidoc: WARNING: adding-packages-gettext.adoc: line 41: list item index: expected 3 got 1
The reason is that we use the same index to tell asciidoc to
automatically number items.
However, the official way to provide an automatic index is to write no
index:
https://docs.asciidoctor.org/asciidoc/latest/lists/ordered/
[...] since the numbering is obvious, the AsciiDoc processor will
insert the numbers for you if you omit them:
[...]
If you number the ordered list explicitly, you have to manually keep
the list numerals sequential. Otherwise, you will get a warning.
So, abide by the documentation, and drop the repeating indices to
ordered lists where we want automatic numbering.
Note that there is another ordered list, in adding-packages-directory.adoc,
but it does use explicit, sequential numbering. For consistency within
the whole document, we also convert it.
To avoid extra useless churn, the indentation of the items is not
changed to match the elided indices.
Signed-off-by: Yann E. MORIN <yann.morin.1998@free.fr>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2024-02-10 22:24:55 +01:00
|
|
|
. Add +$(TARGET_NLS_DEPENDENCIES)+ to the package
|
2017-07-04 11:26:28 +02:00
|
|
|
+<pkg>_DEPENDENCIES+ variable. This addition should be done
|
|
|
|
|
unconditionally: the value of this variable is automatically
|
|
|
|
|
adjusted by the core infrastructure to contain the relevant list of
|
|
|
|
|
packages. If NLS support is disabled, this variable is empty. If
|
|
|
|
|
NLS support is enabled, this variable contains +host-gettext+ so
|
|
|
|
|
that tools needed to compile translation files are available on the
|
|
|
|
|
host. In addition, if 'uClibc' or 'musl' are used, this variable
|
|
|
|
|
also contains +gettext+ in order to get the full-blown 'gettext'
|
|
|
|
|
implementation.
|
|
|
|
|
|
doc/manual: fixup ordered lists
With recent asiidoc versions (at least 10.2.0 is known to report that),
rendering the manual yields a few warnings related to ordered lists:
asciidoc: WARNING: customize-quick-guide.adoc: line 13: list item index: expected 2 got 1
asciidoc: WARNING: customize-quick-guide.adoc: line 15: list item index: expected 3 got 1
[...]
asciidoc: WARNING: customize-quick-guide.adoc: line 65: list item index: expected 13 got 1
asciidoc: WARNING: customize-quick-guide.adoc: line 66: list item index: expected 14 got 1
asciidoc: WARNING: adding-packages-gettext.adoc: line 30: list item index: expected 2 got 1
asciidoc: WARNING: adding-packages-gettext.adoc: line 41: list item index: expected 3 got 1
The reason is that we use the same index to tell asciidoc to
automatically number items.
However, the official way to provide an automatic index is to write no
index:
https://docs.asciidoctor.org/asciidoc/latest/lists/ordered/
[...] since the numbering is obvious, the AsciiDoc processor will
insert the numbers for you if you omit them:
[...]
If you number the ordered list explicitly, you have to manually keep
the list numerals sequential. Otherwise, you will get a warning.
So, abide by the documentation, and drop the repeating indices to
ordered lists where we want automatic numbering.
Note that there is another ordered list, in adding-packages-directory.adoc,
but it does use explicit, sequential numbering. For consistency within
the whole document, we also convert it.
To avoid extra useless churn, the indentation of the items is not
changed to match the elided indices.
Signed-off-by: Yann E. MORIN <yann.morin.1998@free.fr>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2024-02-10 22:24:55 +01:00
|
|
|
. If needed, add +$(TARGET_NLS_LIBS)+ to the linker flags, so that
|
2017-07-04 11:26:28 +02:00
|
|
|
the package gets linked with +libintl+. This is generally not
|
|
|
|
|
needed with 'autotools' packages as they usually detect
|
|
|
|
|
automatically that they should link with +libintl+. However,
|
|
|
|
|
packages using other build systems, or problematic autotools-based
|
|
|
|
|
packages may need this. +$(TARGET_NLS_LIBS)+ should be added
|
|
|
|
|
unconditionally to the linker flags, as the core automatically
|
|
|
|
|
makes it empty or defined to +-lintl+ depending on the
|
|
|
|
|
configuration.
|
|
|
|
|
|
|
|
|
|
No changes should be made to the +Config.in+ file to support NLS.
|
|
|
|
|
|
|
|
|
|
Finally, certain packages need some gettext utilities on the target,
|
2014-08-16 15:47:22 +02:00
|
|
|
such as the +gettext+ program itself, which allows to retrieve
|
2017-07-04 11:26:28 +02:00
|
|
|
translated strings, from the command line. In such a case, the package
|
2012-11-27 12:59:17 +01:00
|
|
|
should:
|
|
|
|
|
|
2014-08-16 15:47:22 +02:00
|
|
|
* use +select BR2_PACKAGE_GETTEXT+ in their +Config.in+ file,
|
|
|
|
|
indicating in a comment above that it's a runtime dependency only.
|
|
|
|
|
|
|
|
|
|
* not add any +gettext+ dependency in the +DEPENDENCIES+ variable of
|
|
|
|
|
their +.mk+ file.
|
