* [Buildroot] [PATCH 0 of 4 for 2014.08] manual-text generation improvements
@ 2014-08-10 18:35 Thomas De Schampheleire
2014-08-10 18:35 ` [Buildroot] [PATCH 1 of 4 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual' Thomas De Schampheleire
` (3 more replies)
0 siblings, 4 replies; 6+ messages in thread
From: Thomas De Schampheleire @ 2014-08-10 18:35 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>
---
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(-)
^ permalink raw reply [flat|nested] 6+ messages in thread* [Buildroot] [PATCH 1 of 4 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual' 2014-08-10 18:35 [Buildroot] [PATCH 0 of 4 for 2014.08] manual-text generation improvements Thomas De Schampheleire @ 2014-08-10 18:35 ` Thomas De Schampheleire 2014-08-10 18:35 ` [Buildroot] [PATCH 2 of 4 for 2014.08] gendoc infra: add support for asciidoc configuration files Thomas De Schampheleire ` (2 subsequent siblings) 3 siblings, 0 replies; 6+ messages in thread From: Thomas De Schampheleire @ 2014-08-10 18:35 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> --- 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)) ^ permalink raw reply [flat|nested] 6+ messages in thread
* [Buildroot] [PATCH 2 of 4 for 2014.08] gendoc infra: add support for asciidoc configuration files 2014-08-10 18:35 [Buildroot] [PATCH 0 of 4 for 2014.08] manual-text generation improvements Thomas De Schampheleire 2014-08-10 18:35 ` [Buildroot] [PATCH 1 of 4 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual' Thomas De Schampheleire @ 2014-08-10 18:35 ` Thomas De Schampheleire 2014-08-10 18:35 ` [Buildroot] [PATCH 3 of 4 for 2014.08] manual-text: make sure URLs are displayed if a link text was provided Thomas De Schampheleire 2014-08-10 18:35 ` [Buildroot] [PATCH 4 of 4 for 2014.08] manual-text: hide image representations Thomas De Schampheleire 3 siblings, 0 replies; 6+ messages in thread From: Thomas De Schampheleire @ 2014-08-10 18:35 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> --- 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* [Buildroot] [PATCH 3 of 4 for 2014.08] manual-text: make sure URLs are displayed if a link text was provided 2014-08-10 18:35 [Buildroot] [PATCH 0 of 4 for 2014.08] manual-text generation improvements Thomas De Schampheleire 2014-08-10 18:35 ` [Buildroot] [PATCH 1 of 4 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual' Thomas De Schampheleire 2014-08-10 18:35 ` [Buildroot] [PATCH 2 of 4 for 2014.08] gendoc infra: add support for asciidoc configuration files Thomas De Schampheleire @ 2014-08-10 18:35 ` Thomas De Schampheleire 2014-08-12 10:56 ` Thomas De Schampheleire 2014-08-10 18:35 ` [Buildroot] [PATCH 4 of 4 for 2014.08] manual-text: hide image representations Thomas De Schampheleire 3 siblings, 1 reply; 6+ messages in thread From: Thomas De Schampheleire @ 2014-08-10 18:35 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, 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=} [{name}:{target}] +[https-inlinemacro] +{0=} [{name}:{target}] +[ftp-inlinemacro] +{0=} [{name}:{target}] +[file-inlinemacro] +{0=} [{name}:{target}] +[irc-inlinemacro] +{0=} [{name}:{target}] +[mailto-inlinemacro] +{0=} [{name}:{target}] ^ permalink raw reply [flat|nested] 6+ messages in thread
* [Buildroot] [PATCH 3 of 4 for 2014.08] manual-text: make sure URLs are displayed if a link text was provided 2014-08-10 18:35 ` [Buildroot] [PATCH 3 of 4 for 2014.08] manual-text: make sure URLs are displayed if a link text was provided Thomas De Schampheleire @ 2014-08-12 10:56 ` Thomas De Schampheleire 0 siblings, 0 replies; 6+ messages in thread From: Thomas De Schampheleire @ 2014-08-12 10:56 UTC (permalink / raw) To: buildroot 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=} [{name}:{target}] > +[https-inlinemacro] > +{0=} [{name}:{target}] > +[ftp-inlinemacro] > +{0=} [{name}:{target}] > +[file-inlinemacro] > +{0=} [{name}:{target}] > +[irc-inlinemacro] > +{0=} [{name}:{target}] > +[mailto-inlinemacro] > +{0=} [{name}:{target}] I'm going to send a refined version of this patch that removes the brackets in case no link text was provided... ^ permalink raw reply [flat|nested] 6+ messages in thread
* [Buildroot] [PATCH 4 of 4 for 2014.08] manual-text: hide image representations 2014-08-10 18:35 [Buildroot] [PATCH 0 of 4 for 2014.08] manual-text generation improvements Thomas De Schampheleire ` (2 preceding siblings ...) 2014-08-10 18:35 ` [Buildroot] [PATCH 3 of 4 for 2014.08] manual-text: make sure URLs are displayed if a link text was provided Thomas De Schampheleire @ 2014-08-10 18:35 ` Thomas De Schampheleire 3 siblings, 0 replies; 6+ messages in thread From: Thomas De Schampheleire @ 2014-08-10 18:35 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> --- 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=} [{name}:{target}] [mailto-inlinemacro] {0=} [{name}:{target}] + +# Hide image representation from text manual +[image-inlinemacro] +{empty} +[image-blockmacro] +{empty} ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2014-08-12 10:56 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2014-08-10 18:35 [Buildroot] [PATCH 0 of 4 for 2014.08] manual-text generation improvements Thomas De Schampheleire 2014-08-10 18:35 ` [Buildroot] [PATCH 1 of 4 for 2014.08] gendoc infra: use $(pkgname) instead of explicitly passing 'manual' Thomas De Schampheleire 2014-08-10 18:35 ` [Buildroot] [PATCH 2 of 4 for 2014.08] gendoc infra: add support for asciidoc configuration files Thomas De Schampheleire 2014-08-10 18:35 ` [Buildroot] [PATCH 3 of 4 for 2014.08] manual-text: make sure URLs are displayed if a link text was provided Thomas De Schampheleire 2014-08-12 10:56 ` Thomas De Schampheleire 2014-08-10 18:35 ` [Buildroot] [PATCH 4 of 4 for 2014.08] manual-text: hide image representations Thomas De Schampheleire
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.