manual-text generation improvements
PATCH v2 1/1 manual-text generation improvements
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.
---
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(-)
PATCH v2 1/1 gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
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.
---
v2: no changes
docs/manual/manual.mk | 18 +++++++++--------- 1 files changed, 9 insertions(+), 9 deletions(-)
docs/manual/manual.mk +9 -9
@@ -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))
PATCH v2 1/1 gendoc infra: add support for asciidoc configuration files
In reply to Thomas De SchampheleireThis 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.
---
v2: no changes
docs/manual/manual.mk | 8 +++++++- 1 files changed, 7 insertions(+), 1 deletions(-)
docs/manual/manual.mk +7 -1
@@ -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
PATCH v2 1/1 manual-text: make sure URLs are displayed if a link text was provided
In reply to Thomas De SchampheleireWhen 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.
---
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(-)
docs/manual/asciidoc-text.conf new file +17 -0
@@ -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? [}{name}:{target}{0?]} +[https-inlinemacro] +{0=}{0? [}{name}:{target}{0?]} +[ftp-inlinemacro] +{0=}{0? [}{name}:{target}{0?]} +[file-inlinemacro] +{0=}{0? [}{name}:{target}{0?]} +[irc-inlinemacro] +{0=}{0? [}{name}:{target}{0?]} +[mailto-inlinemacro] +{0=}{0? [}{name}:{target}{0?]}
PATCH v2 1/1 manual-text: hide image representations
In reply to Thomas De SchampheleireImages 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.
---
v2: no changes
docs/manual/asciidoc-text.conf | 6 ++++++ 1 files changed, 6 insertions(+), 0 deletions(-)
docs/manual/asciidoc-text.conf +6 -0
@@ -15,3 +15,9 @@ {0=}{0? [}{name}:{target}{0?]} [mailto-inlinemacro] {0=}{0? [}{name}:{target}{0?]} + +# Hide image representation from text manual +[image-inlinemacro] +{empty} +[image-blockmacro] +{empty}
PATCH v2 1/1 gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
In reply to Thomas De SchampheleireThomas, All,
On 2014-08-12 20:11 +0200, Thomas De Schampheleire spake thusly:
Quoted 15 lines
In the gendoc infrastructure, using an assignment of the form
FOO = docs/$(1)/barinside
GENDOC_INNERdoes 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.
Quoted 3 lines
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.
Quoted 41 lines
Signed-off-by Thomas De Schampheleire <[email protected]>---
v2: no changesdocs/manual/manual.mk | 18 +++++++++--------- 1 files changed, 9 insertions(+), 9 deletions(-)diff -r
3bcf63a46bc1-r8a3834f24594docs/manual/manual.mkdocs/manual/manual.mk +9
-9@@ -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
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | 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. | '------------------------------^-------^------------------^--------------------'
PATCH v2 1/1 gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
Thomas, All,
On 2014-08-12 22:32 +0200, Yann E. MORIN spake thusly:
Quoted 20 lines
On 2014-08-12 20:11 +0200, Thomas De Schampheleire spake thusly:
Quoted 15 lines
In the gendoc infrastructure, using an assignment of the form
FOO = docs/$(1)/barinside
GENDOC_INNERdoes 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.Quoted 3 lines
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.
Quoted 6 lines
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.
Quoted 53 lines
Quoted 41 lines
Signed-off-by Thomas De Schampheleire <[email protected]>---
v2: no changesdocs/manual/manual.mk | 18 +++++++++--------- 1 files changed, 9 insertions(+), 9 deletions(-)diff -r
3bcf63a46bc1-r8a3834f24594docs/manual/manual.mkdocs/manual/manual.mk +9
-9@@ -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/buildrootSignature · 10 lines
.-----------------.--------------------.------------------.--------------------. | 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
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | 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. | '------------------------------^-------^------------------^--------------------'
PATCH v2 1/1 gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
"Yann E. MORIN" <[email protected]> schreef:
Quoted 30 lines
Thomas, All,
On 2014-08-12 22:32 +0200, Yann E. MORIN spake thusly:
Quoted 20 lines
On 2014-08-12 20:11 +0200, Thomas De Schampheleire spake thusly:
Quoted 15 lines
In the gendoc infrastructure, using an assignment of the form
FOO = docs/$(1)/barinside
GENDOC_INNERdoes 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.Quoted 3 lines
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.
Quoted 6 lines
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.
Quoted 7 lines
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
PATCH v2 1/1 gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
Thomas, All,
On 2014-08-13 09:43 +0200, Thomas De Schampheleire spake thusly:
Quoted 46 lines
"Yann E. MORIN" <[email protected]> schreef:
Quoted 30 lines
Thomas, All,
On 2014-08-12 22:32 +0200, Yann E. MORIN spake thusly:
Quoted 20 lines
On 2014-08-12 20:11 +0200, Thomas De Schampheleire spake thusly:
Quoted 15 lines
In the gendoc infrastructure, using an assignment of the form
FOO = docs/$(1)/barinside
GENDOC_INNERdoes 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.Quoted 3 lines
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.
Quoted 6 lines
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.Quoted 7 lines
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)
Quoted 7 lines
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.
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | 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. | '------------------------------^-------^------------------^--------------------'