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
|
|
|
|
2017-07-04 11:26:28 +02:00
|
|
|
1. Ensure NLS support is enabled when +BR2_SYSTEM_ENABLE_NLS=y+. This
|
|
|
|
|
is done automatically for 'autotools' packages and therefore should
|
|
|
|
|
only be done for packages using other package infrastructures.
|
|
|
|
|
|
|
|
|
|
1. Add +$(TARGET_NLS_DEPENDENCIES)+ to the package
|
|
|
|
|
+<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.
|
|
|
|
|
|
|
|
|
|
1. If needed, add +$(TARGET_NLS_LIBS)+ to the linker flags, so that
|
|
|
|
|
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.
|
