manual-text generation improvements
PATCH v3 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, three 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.
---
v3: fix 'make manual' without .config (extra patch)
v2: refine patch 4 (changing URLs)
Thomas De Schampheleire (5)
Makefile: unconditionally include pkg-utils.mk
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
Makefile | 2 ++ docs/manual/asciidoc-text.conf | 23 +++++++++++++++++++++++ docs/manual/manual.mk | 26 ++++++++++++++++---------- package/Makefile.in | 1 - 4 files changed, 41 insertions(+), 11 deletions(-)
PATCH v3 1/1 Makefile: unconditionally include pkg-utils.mk
Currently, pkg-utils.mk (included via package/Makefile.in) is only included when a configuration file already exists. This means that none of the utilities it defines are available without .config.
In particular:
- the MESSAGE macro, causing pretty build output. Since some make targets can be run even without .config, like 'make manual', not having this pretty printing is odd.
- pkgname, pkgdir: in a subsequent patch, these functions will be used for the generation of the manual, and since this should work also without .config, we need these functions to be available.
This patch moves the include of pkg-utils.mk from package/Makefile.in to Makefile, outside of the check for .config.
This is a quick fix. The full solution involves to minimize the amount of Makefile code that is guarded by a check on .config. This approach will be taken in the 2014.11 release cycle.
---
v3: new patch, fixing the issue detected by Yann that 'make manual' no longer worked without .config
Makefile | 2 ++ package/Makefile.in | 1 - 2 files changed, 2 insertions(+), 1 deletions(-)
Makefile +2 -0
@@ -271,6 +271,8 @@ # Causes breakage with packages that needs host-ruby unexport RUBYOPT +include package/pkg-utils.mk + ifeq ($(BR2_HAVE_DOT_CONFIG),y) ################################################################################
package/Makefile.in +0 -1
@@ -385,7 +385,6 @@ SHARED_STATIC_LIBS_OPTS = --enable-static --enable-shared endif -include package/pkg-utils.mk include package/pkg-download.mk include package/pkg-autotools.mk include package/pkg-cmake.mk
PATCH v3 1/1 gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
In reply to Thomas De SchampheleireIn 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.
---
v3: no changes
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 v3 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.
---
v3: no changes
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 v3 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.
---
v3: no changes
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 v3 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.
---
v3: no changes
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 v3 1/1 Makefile: unconditionally include pkg-utils.mk
In reply to Thomas De SchampheleireQuoted 13 lines · Thomas De Schampheleire
Currently, pkg-utils.mk (included via package/Makefile.in) is only included when a configuration file already exists. This means that none of the utilities it defines are available without .config.
In particular:
- the MESSAGE macro, causing pretty build output. Since some make targets can be run even without .config, like 'make manual', not having this pretty printing is odd.- pkgname, pkgdir: in a subsequent patch, these functions will be used for the generation of the manual, and since this should work also without .config, we need these functions to be available.
Quoted 8 lines
This patch moves the include of pkg-utils.mk from package/Makefile.in to
Makefile, outside of the check for .config.This is a quick fix. The full solution involves to minimize the amount of
Makefilecode that is guarded by a check on .config. This approach will be taken in the 2014.11 release cycle.Signed-off-by Thomas De Schampheleire <[email protected]>
Regards,
--
Samuel
PATCH v3 1/1 gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
In reply to Thomas De SchampheleireQuoted 15 lines · Thomas De Schampheleire
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 5 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.
Signed-off-by Thomas De Schampheleire <[email protected]>
Regards,
--
Samuel
PATCH v3 1/1 gendoc infra: add support for asciidoc configuration files
In reply to Thomas De SchampheleireQuoted 9 lines · 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 <[email protected]>
Regards,
Signature · 1 line
Samuel
PATCH v3 1/1 manual-text: make sure URLs are displayed if a link text was provided
In reply to Thomas De SchampheleireQuoted 6 lines · 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.
Quoted 8 lines
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 <[email protected]>
Regards,
Signature · 1 line
Samuel
PATCH v3 1/1 manual-text: hide image representations
In reply to Thomas De SchampheleireQuoted 9 lines · 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.pngAvoid this by setting the image representation macros to {empty} in manual-text.
Signed-off-by Thomas De Schampheleire <[email protected]>
Regards,
Signature · 1 line
Samuel
PATCH v3 1/1 gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
In reply to Thomas De SchampheleireHi Thomas,
Actually, it's a nack :-/
As is, this patch breaks the clean target, but nothing scary of course ;-)
Quoted 36 lines · Thomas De Schampheleire
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.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 <[email protected]>---
v3: no changes
v2: no changesdocs/manual/manual.mk | 18 +++++++++--------- 1 files changed, 9 insertions(+), 9 deletions(-)diff -r
9000c07087a5-rf7050051dd5adocs/manual/manual.mkdocs/manual/manual.mk Sat Aug 09 18:18:58 2014 +0200 renamed from docs/manual/manual.mk Wed Aug 13 11:30:25 2014 +0200 +0
-1@@ -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")
docs/manual/manual.mk Sat Aug 09 18:18:58 2014 +0200 line 86
Quoted 10 lines
docs/manual/manual.mk Sat Aug 09 18:18:58 2014 +0200 renamed from docs/manual/manual.mk Wed Aug 13 11:30:25 2014 +0200 +5
-4-$(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
Just here ^^^ , you missed a substitution.
With this fix, it's works fine.
Quoted 11 lines
docs/manual/manual.mk Sat Aug 09 18:18:58 2014 +0200 renamed from docs/manual/manual.mk Wed Aug 13 11:30:25 2014 +0200 +4
-4-$(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))
Quoted 4 lines
_______________________________________________
buildroot mailing list
buildroot at busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot
Regards,
Signature · 1 line
Samuel
PATCH v3 1/1 gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
In reply to Thomas De SchampheleireHi Thomas,
Actually, it's a nack :-/
As is, this patch breaks the clean target, but nothing scary of course ;-)
Quoted 36 lines · Thomas De Schampheleire
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.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 <[email protected]>---
v3: no changes
v2: no changesdocs/manual/manual.mk | 18 +++++++++--------- 1 files changed, 9 insertions(+), 9 deletions(-)diff -r
9000c07087a5-rf7050051dd5adocs/manual/manual.mkdocs/manual/manual.mk Sat Aug 09 18:18:58 2014 +0200 renamed from docs/manual/manual.mk Wed Aug 13 11:30:25 2014 +0200 +0
-1@@ -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")
docs/manual/manual.mk Sat Aug 09 18:18:58 2014 +0200 line 86
Quoted 10 lines
docs/manual/manual.mk Sat Aug 09 18:18:58 2014 +0200 renamed from docs/manual/manual.mk Wed Aug 13 11:30:25 2014 +0200 +5
-4-$(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
Just here ^^^ , you missed a substitution.
With this fix, it's works fine.
Quoted 11 lines
docs/manual/manual.mk Sat Aug 09 18:18:58 2014 +0200 renamed from docs/manual/manual.mk Wed Aug 13 11:30:25 2014 +0200 +4
-4-$(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))
Quoted 4 lines
_______________________________________________
buildroot mailing list
buildroot at busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot
Regards,
Signature · 1 line
Samuel
PATCH v3 1/1 gendoc infra: use $(pkgname) instead of explicitly passing 'manual'
In reply to Thomas De SchampheleireThomas, All,
On 2014-08-13 21:25 +0200, Thomas De Schampheleire spake thusly:
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.
I would be very much interested to use this GENDOC infrastructure from br2-external too, to generate another manual.
I'll poke at that when time permits (soon, probably.)
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. | '------------------------------^-------^------------------^--------------------'