[Buildroot] [PATCH] docs/manual: document both user-facing br2-external variables

[Buildroot] [PATCH] docs/manual: document both user-facing br2-external variables

[Yann E. MORIN]

While BR2_EXTERNAL_<NAME>_PATH was already documented, it was not
made obvious that it could be reused in post-biuld, post-image and
in-fakeroot scripts.

The BR2_EXTERNAL_<NAME>_DESC variable was not documented at all.

Update the manual to fix this.

Note: a2x chokes on this:

    .Note:
    Both +BR2_EXTERNAL_$(NAME)_PATH+ and +BR2_EXTERNAL_$(NAME)_DESC+ are
      available [...]

and spits out a totally useless error message:

    a2x: ERROR: "xsltproc" --stringparam toc.section.depth 1 --stringparam
    callout.graphics 0 --stringparam navig.graphics 0 --stringparam
    admon.textlabel 1 --stringparam admon.graphic 0 --stringparam
    chunk.section.depth 0 --output "/home/ymorin/dev/buildroot/O/docs/manual/manual.html"
    "/etc/asciidoc/docbook-xsl/xhtml.xsl"
    "/home/ymorin/dev/buildroot/O/docs/manual/manual.xml" returned
    non-zero exit status 6

So, we had to resort to using different quoting styles for each
variables. They are not semantically equivalent, but the rendering
is the same with the default CSS (which we are using). That's gonna
be good-enough for now...

Reported-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Cc: Beno?t Allard <benoit.allard@greenbone.net>
---
 docs/manual/customize-outside-br.txt | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt
index 56c2c8a..99c38f4 100644
--- a/docs/manual/customize-outside-br.txt
+++ b/docs/manual/customize-outside-br.txt
@@ -120,7 +120,8 @@ Since it is possible to use multiple br2-external trees at once, this
    and is used when displaying information about a br2-external tree (e.g.
    above the list of defconfig files, or as the prompt in the menuconfig);
    as such, it should relatively brief (40 chars is probably a good upper
-   limit).
+   limit). The description is available in the +BR2_EXTERNAL_$(NAME)_DESC+
+   variable.
 
 Examples of names and the corresponding +BR2_EXTERNAL_$(NAME)_PATH+
 variables:
@@ -130,6 +131,12 @@ variables:
 
 In the following examples, it is assumed the name to be set to +BAR_42+.
 
+.Note:
+Both +BR2_EXTERNAL_$(NAME)_PATH+ and `BR2_EXTERNAL_$(NAME)_DESC` are
+  available in the Kconfig files and the Makefiles. They are also
+  exported in the environment so are available to post-build, post-image
+  and in-fakeroot scripts.
+
 ===== The +Config.in+ and +external.mk+ files
 
 Those files (which may each be empty) can be used to define package
-- 
2.7.4

[Buildroot] [PATCH] docs/manual: document both user-facing br2-external variables

[Thomas Petazzoni]

Hello,

On Wed, 19 Oct 2016 22:56:05 +0200, Yann E. MORIN wrote:
> While BR2_EXTERNAL_<NAME>_PATH was already documented, it was not
> made obvious that it could be reused in post-biuld, post-image and
> in-fakeroot scripts.
> 
> The BR2_EXTERNAL_<NAME>_DESC variable was not documented at all.
> 
> Update the manual to fix this.
> 
> Note: a2x chokes on this:
> 
>     .Note:
>     Both +BR2_EXTERNAL_$(NAME)_PATH+ and +BR2_EXTERNAL_$(NAME)_DESC+ are
>       available [...]
> 
> and spits out a totally useless error message:
> 
>     a2x: ERROR: "xsltproc" --stringparam toc.section.depth 1 --stringparam
>     callout.graphics 0 --stringparam navig.graphics 0 --stringparam
>     admon.textlabel 1 --stringparam admon.graphic 0 --stringparam
>     chunk.section.depth 0 --output "/home/ymorin/dev/buildroot/O/docs/manual/manual.html"
>     "/etc/asciidoc/docbook-xsl/xhtml.xsl"
>     "/home/ymorin/dev/buildroot/O/docs/manual/manual.xml" returned
>     non-zero exit status 6
> 
> So, we had to resort to using different quoting styles for each
> variables. They are not semantically equivalent, but the rendering
> is the same with the default CSS (which we are using). That's gonna
> be good-enough for now...
> 
> Reported-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
> Cc: Beno?t Allard <benoit.allard@greenbone.net>
> ---
>  docs/manual/customize-outside-br.txt | 9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)

Applied to master, thanks.

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com