[Buildroot] [PATCH 0 of 4 for 2014.08] manual-text generation improvements

[Buildroot] [PATCH 0 of 4 for 2014.08] manual-text generation improvements

[Thomas De Schampheleire]

This patch series makes some improvements to the generation of the text
version of the manual:
- make sure that URLs are visible
- remove the 'logo' (logo.png) reference

To achieve this, two preparatory patches are needed.

Note that this series stands on its own, it can already be applied.
A subsequent series will make structural and content-wise changes to the
manual itself.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
Thomas De Schampheleire (4)
  gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
  gendoc infra: add support for asciidoc configuration files
  manual-text: make sure URLs are displayed if a link text was provided
  manual-text: hide image representations

 docs/manual/asciidoc-text.conf |  19 +++++++++++++++++++
 docs/manual/manual.mk          |  26 ++++++++++++++++----------
 2 files changed, 35 insertions(+), 10 deletions(-)

[Buildroot] [PATCH 1 of 4 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual'

[Thomas De Schampheleire]

In the gendoc infrastructure, using an assignment of the form
    FOO = docs/$(1)/bar
inside GENDOC_INNER does not work as expected: the $(1) value is empty here
and the value of FOO becomes 'docs//bar'.

Parameters $(2), $(3), etc. do not have this problem. The specific thing
about $(1) is that it is a parameter to GENDOC itself (indicating the
document to create) and passed transparently to GENDOC_INNER.

This is different from the package infrastructures, where $(1) is set from
$(pkgname). In fact, the same strategy could be used by the gendoc
infrastructure as well, as $(pkgname) resolves to 'manual' for file
docs/manual/manual.mk. This has the advantage that the described problem
does not occur.

Note that this means that if we want to use the same GENDOC infrastructure
for another document, it will have to reside in a separate directory than
the manual.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/manual.mk |  18 +++++++++---------
 1 files changed, 9 insertions(+), 9 deletions(-)

diff -r 3bcf63a46bc1 -r 6a056a337e1b docs/manual/manual.mk
--- a/docs/manual/manual.mk	Tue Aug 05 18:25:11 2014 -0300
+++ b/docs/manual/manual.mk	Sat Aug 09 18:18:58 2014 +0200
@@ -78,16 +78,16 @@
 # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
 ################################################################################
 define GENDOC
-$(call GENDOC_INNER,$(1),xhtml,html,html,HTML,--xsltproc-opts "--stringparam toc.section.depth 2")
-$(call GENDOC_INNER,$(1),chunked,split-html,chunked,split HTML,--xsltproc-opts "--stringparam toc.section.depth 2")
-$(call GENDOC_INNER,$(1),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
-$(call GENDOC_INNER,$(1),text,text,text,text)
-$(call GENDOC_INNER,$(1),epub,epub,epub,ePUB)
+$(call GENDOC_INNER,$(pkgname),xhtml,html,html,HTML,--xsltproc-opts "--stringparam toc.section.depth 2")
+$(call GENDOC_INNER,$(pkgname),chunked,split-html,chunked,split HTML,--xsltproc-opts "--stringparam toc.section.depth 2")
+$(call GENDOC_INNER,$(pkgname),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
+$(call GENDOC_INNER,$(pkgname),text,text,text,text)
+$(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB)
 clean: $(1)-clean
-$(1)-clean:
-	$$(Q)$$(RM) -rf $$(O)/docs/$(1)
-.PHONY: $(1) $(1)-clean manual-update-lists
+$(pkgname)-clean:
+	$$(Q)$$(RM) -rf $$(O)/docs/$(pkgname)
+.PHONY: $(pkgname) $(pkgname)-clean manual-update-lists
 endef
 
 MANUAL_SOURCES = $(sort $(wildcard docs/manual/*.txt) $(wildcard docs/images/*))
-$(eval $(call GENDOC,manual))
+$(eval $(call GENDOC))

[Buildroot] [PATCH 2 of 4 for 2014.08] gendoc infra: add support for asciidoc configuration files

[Thomas De Schampheleire]

This patch introduces support for asciidoc configuration files, specific for
each output format (html, text, pdf, ...). This is useful to make certain
tweaks in the document generation.

If a file docs/manual/asciidoc-<format>.conf is present, it is passed to
asciidoc as configuration file. If no file for the current format is
present, the options passed to asciidoc are empty.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/manual.mk |  8 +++++++-
 1 files changed, 7 insertions(+), 1 deletions(-)

diff -r 6a056a337e1b -r 6e36b7e6851b docs/manual/manual.mk
--- a/docs/manual/manual.mk	Sat Aug 09 18:18:58 2014 +0200
+++ b/docs/manual/manual.mk	Sat Aug 09 12:20:16 2014 +0200
@@ -56,6 +56,11 @@
 
 manual-check-dependencies-$(3):
 
+MANUAL_$(2)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(2).conf
+ifneq ($$(wildcard $$(MANUAL_$(2)_ASCIIDOC_CONF)),)
+MANUAL_$(2)_ASCIIDOC_OPTS += -f $$(MANUAL_$(2)_ASCIIDOC_CONF)
+endif
+
 $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \
 			   $$($$(call UPPERCASE,$(1))_SOURCES) \
 			   manual-check-dependencies \
@@ -65,7 +70,8 @@
 	$$(Q)mkdir -p $$(@D)/.build
 	$$(Q)rsync -au docs/$(1)/*.txt $$(@D)/.build
 	$$(Q)a2x $(6) -f $(2) -d book -L -r $$(TOPDIR)/docs/images \
-	        -D $$(@D) $$(@D)/.build/$(1).txt
+	        -D $$(@D) $$(@D)/.build/$(1).txt \
+	        --asciidoc-opts="$$(MANUAL_$(2)_ASCIIDOC_OPTS)"
 	-$$(Q)rm -rf $$(@D)/.build
 endef
 

[Buildroot] [PATCH 3 of 4 for 2014.08] manual-text: make sure URLs are displayed if a link text was provided

[Thomas De Schampheleire]

When the asciidoc source contain URLs of the form:
    http://example.com[An example website]
the text representation of the manual would only contain:
    An example website
without displaying the actual URL.

This patch adds an asciidoc configuration file that sets the inline macros
for several URL types so that the display becomes:
    An example website [http://example.com]
For URLs where no link text was provided, the display becomes:
    [http://example.com]
which is the same as before, except for the surrounding brackets.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/asciidoc-text.conf |  13 +++++++++++++
 1 files changed, 13 insertions(+), 0 deletions(-)

diff -r 6e36b7e6851b -r a891fa8b7ca9 docs/manual/asciidoc-text.conf
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/manual/asciidoc-text.conf	Sat Aug 09 19:42:30 2014 +0200
@@ -0,0 +1,13 @@
+# For hyperlinks, show 'link text [URL]' (if link text provided) or [URL]
+[http-inlinemacro]
+{0=} &#91;{name}:{target}&#93;
+[https-inlinemacro]
+{0=} &#91;{name}:{target}&#93;
+[ftp-inlinemacro]
+{0=} &#91;{name}:{target}&#93;
+[file-inlinemacro]
+{0=} &#91;{name}:{target}&#93;
+[irc-inlinemacro]
+{0=} &#91;{name}:{target}&#93;
+[mailto-inlinemacro]
+{0=} &#91;{name}:{target}&#93;

[Buildroot] [PATCH 3 of 4 for 2014.08] manual-text: make sure URLs are displayed if a link text was provided

[Thomas De Schampheleire]

On Sun, Aug 10, 2014 at 8:35 PM, Thomas De Schampheleire
<patrickdepinguin@gmail.com> wrote:
> When the asciidoc source contain URLs of the form:
>     http://example.com[An example website]
> the text representation of the manual would only contain:
>     An example website
> without displaying the actual URL.
>
> This patch adds an asciidoc configuration file that sets the inline macros
> for several URL types so that the display becomes:
>     An example website [http://example.com]
> For URLs where no link text was provided, the display becomes:
>     [http://example.com]
> which is the same as before, except for the surrounding brackets.
>
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
>
> ---
>  docs/manual/asciidoc-text.conf |  13 +++++++++++++
>  1 files changed, 13 insertions(+), 0 deletions(-)
>
> diff -r 6e36b7e6851b -r a891fa8b7ca9 docs/manual/asciidoc-text.conf
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/docs/manual/asciidoc-text.conf    Sat Aug 09 19:42:30 2014 +0200
> @@ -0,0 +1,13 @@
> +# For hyperlinks, show 'link text [URL]' (if link text provided) or [URL]
> +[http-inlinemacro]
> +{0=} &#91;{name}:{target}&#93;
> +[https-inlinemacro]
> +{0=} &#91;{name}:{target}&#93;
> +[ftp-inlinemacro]
> +{0=} &#91;{name}:{target}&#93;
> +[file-inlinemacro]
> +{0=} &#91;{name}:{target}&#93;
> +[irc-inlinemacro]
> +{0=} &#91;{name}:{target}&#93;
> +[mailto-inlinemacro]
> +{0=} &#91;{name}:{target}&#93;

I'm going to send a refined version of this patch that removes the
brackets in case no link text was provided...

[Buildroot] [PATCH 4 of 4 for 2014.08] manual-text: hide image representations

[Thomas De Schampheleire]

Images specified in the asciidoc sources (currently only the logo) are
displayed as the file name in the text version of the manual. This causes an
odd line to appear:
    logo.png

Avoid this by setting the image representation macros to {empty} in
manual-text.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/asciidoc-text.conf |  6 ++++++
 1 files changed, 6 insertions(+), 0 deletions(-)

diff -r a891fa8b7ca9 -r d17274964bab docs/manual/asciidoc-text.conf
--- a/docs/manual/asciidoc-text.conf	Sat Aug 09 19:42:30 2014 +0200
+++ b/docs/manual/asciidoc-text.conf	Sun Aug 10 17:55:54 2014 +0200
@@ -11,3 +11,9 @@
 {0=} &#91;{name}:{target}&#93;
 [mailto-inlinemacro]
 {0=} &#91;{name}:{target}&#93;
+
+# Hide image representation from text manual
+[image-inlinemacro]
+{empty}
+[image-blockmacro]
+{empty}