Buildroot Archive on lore.kernel.org
 help / color / mirror / Atom feed
* [Buildroot] [PATCH 0 of 4 v2 for 2014.08] manual-text generation improvements
@ 2014-08-12 18:11 Thomas De Schampheleire
  2014-08-12 18:11 ` [Buildroot] [PATCH 1 of 4 v2 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual' Thomas De Schampheleire
                   ` (3 more replies)
  0 siblings, 4 replies; 9+ messages in thread
From: Thomas De Schampheleire @ 2014-08-12 18:11 UTC (permalink / raw)
  To: buildroot


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>

---
v2: refine patch 3 (changing URLs)

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 |  23 +++++++++++++++++++++++
 docs/manual/manual.mk          |  26 ++++++++++++++++----------
 2 files changed, 39 insertions(+), 10 deletions(-)

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [Buildroot] [PATCH 1 of 4 v2 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
  2014-08-12 18:11 [Buildroot] [PATCH 0 of 4 v2 for 2014.08] manual-text generation improvements Thomas De Schampheleire
@ 2014-08-12 18:11 ` Thomas De Schampheleire
  2014-08-12 20:32   ` Yann E. MORIN
  2014-08-12 18:11 ` [Buildroot] [PATCH 2 of 4 v2 for 2014.08] gendoc infra: add support for asciidoc configuration files Thomas De Schampheleire
                   ` (2 subsequent siblings)
  3 siblings, 1 reply; 9+ messages in thread
From: Thomas De Schampheleire @ 2014-08-12 18:11 UTC (permalink / raw)
  To: buildroot

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>

---
v2: no changes

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

diff -r 3bcf63a46bc1 -r 8a3834f24594 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))

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [Buildroot] [PATCH 2 of 4 v2 for 2014.08] gendoc infra: add support for asciidoc configuration files
  2014-08-12 18:11 [Buildroot] [PATCH 0 of 4 v2 for 2014.08] manual-text generation improvements Thomas De Schampheleire
  2014-08-12 18:11 ` [Buildroot] [PATCH 1 of 4 v2 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual' Thomas De Schampheleire
@ 2014-08-12 18:11 ` Thomas De Schampheleire
  2014-08-12 18:11 ` [Buildroot] [PATCH 3 of 4 v2 for 2014.08] manual-text: make sure URLs are displayed if a link text was provided Thomas De Schampheleire
  2014-08-12 18:11 ` [Buildroot] [PATCH 4 of 4 v2 for 2014.08] manual-text: hide image representations Thomas De Schampheleire
  3 siblings, 0 replies; 9+ messages in thread
From: Thomas De Schampheleire @ 2014-08-12 18:11 UTC (permalink / raw)
  To: buildroot

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>

---
v2: no changes

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

diff -r 8a3834f24594 -r 367601c54918 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
 

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [Buildroot] [PATCH 3 of 4 v2 for 2014.08] manual-text: make sure URLs are displayed if a link text was provided
  2014-08-12 18:11 [Buildroot] [PATCH 0 of 4 v2 for 2014.08] manual-text generation improvements Thomas De Schampheleire
  2014-08-12 18:11 ` [Buildroot] [PATCH 1 of 4 v2 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual' Thomas De Schampheleire
  2014-08-12 18:11 ` [Buildroot] [PATCH 2 of 4 v2 for 2014.08] gendoc infra: add support for asciidoc configuration files Thomas De Schampheleire
@ 2014-08-12 18:11 ` Thomas De Schampheleire
  2014-08-12 18:11 ` [Buildroot] [PATCH 4 of 4 v2 for 2014.08] manual-text: hide image representations Thomas De Schampheleire
  3 siblings, 0 replies; 9+ messages in thread
From: Thomas De Schampheleire @ 2014-08-12 18:11 UTC (permalink / raw)
  To: buildroot

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.

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

---
v2:
- link to relevant documentation (which was hard to find)
- refine so that the display is identical to before when no link text is
  provided.

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

diff -r 367601c54918 -r 9837ad732c42 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,17 @@
+# Refer to following asciidoc documentation:
+#     http://www.methods.co.nz/asciidoc/userguide.html
+# In particular sections "Macros" and "Attribute References"
+#
+# For hyperlinks, show 'link text [URL]' (if link text provided) or 'URL'
+[http-inlinemacro]
+{0=}{0? &#91;}{name}:{target}{0?&#93;}
+[https-inlinemacro]
+{0=}{0? &#91;}{name}:{target}{0?&#93;}
+[ftp-inlinemacro]
+{0=}{0? &#91;}{name}:{target}{0?&#93;}
+[file-inlinemacro]
+{0=}{0? &#91;}{name}:{target}{0?&#93;}
+[irc-inlinemacro]
+{0=}{0? &#91;}{name}:{target}{0?&#93;}
+[mailto-inlinemacro]
+{0=}{0? &#91;}{name}:{target}{0?&#93;}

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [Buildroot] [PATCH 4 of 4 v2 for 2014.08] manual-text: hide image representations
  2014-08-12 18:11 [Buildroot] [PATCH 0 of 4 v2 for 2014.08] manual-text generation improvements Thomas De Schampheleire
                   ` (2 preceding siblings ...)
  2014-08-12 18:11 ` [Buildroot] [PATCH 3 of 4 v2 for 2014.08] manual-text: make sure URLs are displayed if a link text was provided Thomas De Schampheleire
@ 2014-08-12 18:11 ` Thomas De Schampheleire
  3 siblings, 0 replies; 9+ messages in thread
From: Thomas De Schampheleire @ 2014-08-12 18:11 UTC (permalink / raw)
  To: buildroot

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>

---
v2: no changes

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

diff -r 9837ad732c42 -r 3c57cf276290 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
@@ -15,3 +15,9 @@
 {0=}{0? &#91;}{name}:{target}{0?&#93;}
 [mailto-inlinemacro]
 {0=}{0? &#91;}{name}:{target}{0?&#93;}
+
+# Hide image representation from text manual
+[image-inlinemacro]
+{empty}
+[image-blockmacro]
+{empty}

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [Buildroot] [PATCH 1 of 4 v2 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
  2014-08-12 18:11 ` [Buildroot] [PATCH 1 of 4 v2 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual' Thomas De Schampheleire
@ 2014-08-12 20:32   ` Yann E. MORIN
  2014-08-12 20:46     ` Yann E. MORIN
  0 siblings, 1 reply; 9+ messages in thread
From: Yann E. MORIN @ 2014-08-12 20:32 UTC (permalink / raw)
  To: buildroot

Thomas, All,

On 2014-08-12 20:11 +0200, Thomas De Schampheleire spake thusly:
> 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.

This breaks generating the manual:

    $ make manual-html
    make: *** No rule to make target `manual-html'.  Stop.
    $ make manual
    make: *** No rule to make target `manual'.  Stop.

Did I miss something? Was that patch supposed to do that? ;-)

Regards,
Yann E. MORIN.

> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
> 
> ---
> v2: no changes
> 
>  docs/manual/manual.mk |  18 +++++++++---------
>  1 files changed, 9 insertions(+), 9 deletions(-)
> 
> diff -r 3bcf63a46bc1 -r 8a3834f24594 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 mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [Buildroot] [PATCH 1 of 4 v2 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
  2014-08-12 20:32   ` Yann E. MORIN
@ 2014-08-12 20:46     ` Yann E. MORIN
  2014-08-13  7:43       ` Thomas De Schampheleire
  0 siblings, 1 reply; 9+ messages in thread
From: Yann E. MORIN @ 2014-08-12 20:46 UTC (permalink / raw)
  To: buildroot

Thomas, All,

On 2014-08-12 22:32 +0200, Yann E. MORIN spake thusly:
> On 2014-08-12 20:11 +0200, Thomas De Schampheleire spake thusly:
> > 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.
> 
> This breaks generating the manual:
> 
>     $ make manual-html
>     make: *** No rule to make target `manual-html'.  Stop.
>     $ make manual
>     make: *** No rule to make target `manual'.  Stop.

That's because $(pkgname) returns empty, because $(pkgdir) returns
empty, because I do not have a .config file.

So, before this patch, it was possible to build the manual from a
pristine Buildroot tree; now it is no longer possible.

I think that's bad.

Regards,
Yann E. MORIN.

> > Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
> > 
> > ---
> > v2: no changes
> > 
> >  docs/manual/manual.mk |  18 +++++++++---------
> >  1 files changed, 9 insertions(+), 9 deletions(-)
> > 
> > diff -r 3bcf63a46bc1 -r 8a3834f24594 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 mailing list
> > buildroot at busybox.net
> > http://lists.busybox.net/mailman/listinfo/buildroot
> 
> -- 
> .-----------------.--------------------.------------------.--------------------.
> |  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
> | +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
> | +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
> | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
> '------------------------------^-------^------------------^--------------------'
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [Buildroot] [PATCH 1 of 4 v2 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
  2014-08-12 20:46     ` Yann E. MORIN
@ 2014-08-13  7:43       ` Thomas De Schampheleire
  2014-08-13  9:25         ` Yann E. MORIN
  0 siblings, 1 reply; 9+ messages in thread
From: Thomas De Schampheleire @ 2014-08-13  7:43 UTC (permalink / raw)
  To: buildroot

"Yann E. MORIN" <yann.morin.1998@free.fr> schreef:
>Thomas, All,
>
>On 2014-08-12 22:32 +0200, Yann E. MORIN spake thusly:
>> On 2014-08-12 20:11 +0200, Thomas De Schampheleire spake thusly:
>> > 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.
>> 
>> This breaks generating the manual:
>> 
>>     $ make manual-html
>>     make: *** No rule to make target `manual-html'.  Stop.
>>     $ make manual
>>     make: *** No rule to make target `manual'.  Stop.
>
>That's because $(pkgname) returns empty, because $(pkgdir) returns
>empty, because I do not have a .config file.
>
>So, before this patch, it was possible to build the manual from a
>pristine Buildroot tree; now it is no longer possible.
>
>I think that's bad.

Agreed. The problem is that pkg-utils.mk is only
included when a config file is present.
Based on this, I see three possibilities:

1. Include pkg-utils.mk unconditionally from Makefile
 (currently included from package/Makefile.in)

2. Move the definition of pkgname and pkgdir to
 Makefile (outside the check on the config file)

3. Don't use pkgname/pkgdir for the manual
 generation rules, and try to solve the issue with $1 on
 a different way (I feel double dollar signs coming up
 somewhere...)

Best regards,
Thomas

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [Buildroot] [PATCH 1 of 4 v2 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
  2014-08-13  7:43       ` Thomas De Schampheleire
@ 2014-08-13  9:25         ` Yann E. MORIN
  0 siblings, 0 replies; 9+ messages in thread
From: Yann E. MORIN @ 2014-08-13  9:25 UTC (permalink / raw)
  To: buildroot

Thomas, All,

On 2014-08-13 09:43 +0200, Thomas De Schampheleire spake thusly:
> "Yann E. MORIN" <yann.morin.1998@free.fr> schreef:
> >Thomas, All,
> >
> >On 2014-08-12 22:32 +0200, Yann E. MORIN spake thusly:
> >> On 2014-08-12 20:11 +0200, Thomas De Schampheleire spake thusly:
> >> > 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.
> >> 
> >> This breaks generating the manual:
> >> 
> >>     $ make manual-html
> >>     make: *** No rule to make target `manual-html'.  Stop.
> >>     $ make manual
> >>     make: *** No rule to make target `manual'.  Stop.
> >
> >That's because $(pkgname) returns empty, because $(pkgdir) returns
> >empty, because I do not have a .config file.
> >
> >So, before this patch, it was possible to build the manual from a
> >pristine Buildroot tree; now it is no longer possible.
> >
> >I think that's bad.
> 
> Agreed. The problem is that pkg-utils.mk is only
> included when a config file is present.
> Based on this, I see three possibilities:
> 
> 1. Include pkg-utils.mk unconditionally from Makefile
>  (currently included from package/Makefile.in)
> 
> 2. Move the definition of pkgname and pkgdir to
>  Makefile (outside the check on the config file)
> 
> 3. Don't use pkgname/pkgdir for the manual
>  generation rules, and try to solve the issue with $1 on
>  a different way (I feel double dollar signs coming up
>  somewhere...)

I think option 1 is the best.

As far as I cn see, the only parts of pkg-utils that need a .config are
the INFLATE.XXX variables. The rest of the file can well live outside of
the HAS_DOT_CONFIG conditional.

But the same can be said of most other pkg-*.mk files that define
package infrastructures: the definitions in themselves do not need a
.config, not even the build rules in pkg-generic.mk.

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2014-08-13  9:25 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-08-12 18:11 [Buildroot] [PATCH 0 of 4 v2 for 2014.08] manual-text generation improvements Thomas De Schampheleire
2014-08-12 18:11 ` [Buildroot] [PATCH 1 of 4 v2 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual' Thomas De Schampheleire
2014-08-12 20:32   ` Yann E. MORIN
2014-08-12 20:46     ` Yann E. MORIN
2014-08-13  7:43       ` Thomas De Schampheleire
2014-08-13  9:25         ` Yann E. MORIN
2014-08-12 18:11 ` [Buildroot] [PATCH 2 of 4 v2 for 2014.08] gendoc infra: add support for asciidoc configuration files Thomas De Schampheleire
2014-08-12 18:11 ` [Buildroot] [PATCH 3 of 4 v2 for 2014.08] manual-text: make sure URLs are displayed if a link text was provided Thomas De Schampheleire
2014-08-12 18:11 ` [Buildroot] [PATCH 4 of 4 v2 for 2014.08] manual-text: hide image representations Thomas De Schampheleire

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox