| Message ID | 661d747642ce1e9ca884829b0a295faf35933209.1410692670.git.yann.morin.1998@free.fr |
|---|---|
| State | Changes Requested |
| Headers | show |
On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote: > GENDOC_INNER still has one hard-coded path to the document's directory: > the asciidoc .conf files. In this patch you assume that the asciidoc configuration is document-specific, but at least the current contents of asciidoc-text.conf are global IMO: they simply make sure that hyperlinks are represented in a sane way, and that images are not shown (text document only). These are settings that apply to all documents. It can be useful to provide a mechanism for other documents to pass additional configuration files, but at this moment it is not strictly needed. I don't know if it makes sense to already provide a variable for that, or rather wait for a real use case to add it (KISS principle). Awaiting the outcome of this consideration, I did not yet review the patch in detail.
Thomas, All, On 2014-09-22 21:38 +0200, Thomas De Schampheleire spake thusly: > On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote: > > GENDOC_INNER still has one hard-coded path to the document's directory: > > the asciidoc .conf files. > > In this patch you assume that the asciidoc configuration is > document-specific, Well, not really. The code already had: MANUAL_$(2)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(2).conf so the location where the asciidoc-FORMAT.conf was already supposed to be specific to one document. This patch merely removes the assumption that the document is in a sub-directory of docs: docs/$(1)/ --> $(3)/ ($(3) is the directory of the document) > but at least the current contents of > asciidoc-text.conf are global IMO: they simply make sure that > hyperlinks are represented in a sane way, and that images are not > shown (text document only). These are settings that apply to all > documents. I agree. But then, where should we move it? - keep it in docs/manual/ ? That would imply it is specific to our manual. - move it in docs/ ? But docs/ contains our website. - keep docs/manual, move the website to docs/website/ ? This way we could move the asciidoc*.conf into docs/ and is IMHO much cleaner than we have today. > It can be useful to provide a mechanism for other documents to pass > additional configuration files, but at this moment it is not strictly > needed. I don't know if it makes sense to already provide a variable > for that, or rather wait for a real use case to add it (KISS > principle). I already need that, and already implemented it, because I need this asciidoc configuration: [specialwords] emphasizedwords=WORD1 WORD2 > Awaiting the outcome of this consideration, I did not yet review the > patch in detail. OK, here's what I suggest: - add a new variable for documents to pass an asccidoc.conf (done); - add a new variable for documents to pass a format-specific asciidoc-FMT.conf; - keep the current asciidoc-text.conf where it is, and always use it. Then, if we decide to move the website, I can come up with more patches to do so, and move the global asciidoc*.conf files into docs/ Is that OK with you guys? Peter, that would have an impact on the server to generate the nightly manual, so we need your input here. Regards, Yann E. MORIN.
Hi Yann, On Tue, Sep 23, 2014 at 7:21 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote: > Thomas, All, > > On 2014-09-22 21:38 +0200, Thomas De Schampheleire spake thusly: >> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote: >> > GENDOC_INNER still has one hard-coded path to the document's directory: >> > the asciidoc .conf files. >> >> In this patch you assume that the asciidoc configuration is >> document-specific, > > Well, not really. The code already had: > MANUAL_$(2)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(2).conf > > so the location where the asciidoc-FORMAT.conf was already supposed to > be specific to one document. > > This patch merely removes the assumption that the document is in a > sub-directory of docs: > docs/$(1)/ --> $(3)/ ($(3) is the directory of the document) > >> but at least the current contents of >> asciidoc-text.conf are global IMO: they simply make sure that >> hyperlinks are represented in a sane way, and that images are not >> shown (text document only). These are settings that apply to all >> documents. > > I agree. But then, where should we move it? > > - keep it in docs/manual/ ? That would imply it is specific to our > manual. > > - move it in docs/ ? But docs/ contains our website. > > - keep docs/manual, move the website to docs/website/ ? This way we > could move the asciidoc*.conf into docs/ and is IMHO much cleaner > than we have today. I think this proposal is better than the first two. The layout would be docs/ asciidoc setting files website/ manual/ It could be seen as odd to have these asciidoc settings at top-level, next to website that is totally unrelated. An alternative would be something like (forget about the names): docs/ docs/ asciidoc setting files manual/ website/ but that seems very odd. And moving 'website' to top-level buildroot is not very nice either. So I tend to go for docs/ asciidoc setting files website/ manual/ > >> It can be useful to provide a mechanism for other documents to pass >> additional configuration files, but at this moment it is not strictly >> needed. I don't know if it makes sense to already provide a variable >> for that, or rather wait for a real use case to add it (KISS >> principle). > > I already need that, and already implemented it, because I need this > asciidoc configuration: > > [specialwords] > emphasizedwords=WORD1 WORD2 Ok. > >> Awaiting the outcome of this consideration, I did not yet review the >> patch in detail. > > OK, here's what I suggest: > > - add a new variable for documents to pass an asccidoc.conf (done); > - add a new variable for documents to pass a format-specific > asciidoc-FMT.conf; > - keep the current asciidoc-text.conf where it is, and always use it. and also always use a common asciidoc.conf, if it exists, right? > > Then, if we decide to move the website, I can come up with more patches > to do so, and move the global asciidoc*.conf files into docs/ > > Is that OK with you guys? Peter, that would have an impact on the server > to generate the nightly manual, so we need your input here. Yes, if there is agreement on this then I would like to have this changed together / close after merging this gendoc series. Best regards, Thomas
Hi Yann, Thomas, all On Wed, Sep 24, 2014 at 8:54 AM, Thomas De Schampheleire <patrickdepinguin@gmail.com> wrote: > Hi Yann, > > On Tue, Sep 23, 2014 at 7:21 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote: >> Thomas, All, >> >> On 2014-09-22 21:38 +0200, Thomas De Schampheleire spake thusly: >>> On Sun, Sep 14, 2014 at 1:07 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote: >>> > GENDOC_INNER still has one hard-coded path to the document's directory: >>> > the asciidoc .conf files. >>> >>> In this patch you assume that the asciidoc configuration is >>> document-specific, >> >> Well, not really. The code already had: >> MANUAL_$(2)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(2).conf >> >> so the location where the asciidoc-FORMAT.conf was already supposed to >> be specific to one document. >> >> This patch merely removes the assumption that the document is in a >> sub-directory of docs: >> docs/$(1)/ --> $(3)/ ($(3) is the directory of the document) >> >>> but at least the current contents of >>> asciidoc-text.conf are global IMO: they simply make sure that >>> hyperlinks are represented in a sane way, and that images are not >>> shown (text document only). These are settings that apply to all >>> documents. >> >> I agree. But then, where should we move it? >> >> - keep it in docs/manual/ ? That would imply it is specific to our >> manual. >> >> - move it in docs/ ? But docs/ contains our website. >> >> - keep docs/manual, move the website to docs/website/ ? This way we >> could move the asciidoc*.conf into docs/ and is IMHO much cleaner >> than we have today. > > I think this proposal is better than the first two. The layout would be > > docs/ > asciidoc setting files > website/ > manual/ > > It could be seen as odd to have these asciidoc settings at top-level, > next to website that is totally unrelated. > An alternative would be something like (forget about the names): > docs/ > docs/ > asciidoc setting files > manual/ > website/ > I prefer the first layout over the second one. Regards,
Patrick, Samuel, All, On 2014-09-24 08:54 +0200, Thomas De Schampheleire spake thusly: > On Tue, Sep 23, 2014 at 7:21 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote: [--SNIP--] > > I agree. But then, where should we move it? > > > > - keep it in docs/manual/ ? That would imply it is specific to our > > manual. > > > > - move it in docs/ ? But docs/ contains our website. > > > > - keep docs/manual, move the website to docs/website/ ? This way we > > could move the asciidoc*.conf into docs/ and is IMHO much cleaner > > than we have today. > > I think this proposal is better than the first two. The layout would be > > docs/ > asciidoc setting files > website/ > manual/ As Peter (on IRC), Samuel, you and I all prefer this layout, I'm going with that. In fact, I already have the patches moving the website ready for submission. But I'll do in a separate series, so it is easier to handle. Thanks! :-) Regards, Yann E. MORIN.
diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk index befd1ed..9a50e1d 100644 --- a/docs/manual/manual.mk +++ b/docs/manual/manual.mk @@ -53,14 +53,15 @@ MANUAL_XSLTPROC_IS_BROKEN = \ # GENDOC_INNER -- generates the make targets needed to build a specific type of # asciidoc documentation. # -# argument 1 is the name of the document and must be a subdirectory of docs/; -# the top-level asciidoc file must have the same name +# argument 1 is the name of the document and the top-level asciidoc file must +# have the same name # argument 2 is the uppercase name of the document -# argument 3 is the type of document to generate (-f argument of a2x) -# argument 4 is the document type as used in the make target -# argument 5 is the output file extension for the document type -# argument 6 is the human text for the document type -# argument 7 (optional) are extra arguments for a2x +# argument 3 is the directory containing the document +# argument 4 is the type of document to generate (-f argument of a2x) +# argument 5 is the document type as used in the make target +# argument 6 is the output file extension for the document type +# argument 7 is the human text for the document type +# argument 8 (optional) are extra arguments for a2x # # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies. # @@ -68,51 +69,51 @@ MANUAL_XSLTPROC_IS_BROKEN = \ # all variable references except the arguments must be $$-quoted. ################################################################################ define GENDOC_INNER -$(1): $(1)-$(4) -.PHONY: $(1)-$(4) -$(1)-$(4): $$(O)/docs/$(1)/$(1).$(5) +$(1): $(1)-$(5) +.PHONY: $(1)-$(5) +$(1)-$(5): $$(O)/docs/$(1)/$(1).$(6) -$(1)-check-dependencies-$(4): +$(1)-check-dependencies-$(5): -$(2)_$(3)_ASCIIDOC_CONF = docs/$(1)/asciidoc-$(3).conf -ifneq ($$(wildcard $$($(2)_$(3)_ASCIIDOC_CONF)),) -$(2)_$(3)_ASCIIDOC_OPTS += -f $$($(2)_$(3)_ASCIIDOC_CONF) +$(2)_$(4)_ASCIIDOC_CONF = $(3)/asciidoc-$(4).conf +ifneq ($$(wildcard $$($(2)_$(4)_ASCIIDOC_CONF)),) +$(2)_$(4)_ASCIIDOC_OPTS += -f $$($(2)_$(4)_ASCIIDOC_CONF) endif # Handle a2x warning about --destination-dir option only applicable to HTML # based outputs. So: # - use the --destination-dir option if possible (html and split-html), # - otherwise copy the generated manual to the output directory -$(2)_$(3)_A2X_OPTS = -ifneq ($$(filter $(4),html split-html),) -$(2)_$(3)_A2X_OPTS += --destination-dir="$$(@D)" +$(2)_$(4)_A2X_OPTS = +ifneq ($$(filter $(5),html split-html),) +$(2)_$(4)_A2X_OPTS += --destination-dir="$$(@D)" else -define $(2)_$(3)_INSTALL_CMDS - $$(Q)cp -f $$(BUILD_DIR)/$(1)/$(1).$(5) $$(@D) +define $(2)_$(4)_INSTALL_CMDS + $$(Q)cp -f $$(BUILD_DIR)/$(1)/$(1).$(6) $$(@D) endef endif -ifeq ($(5)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y) -$$(O)/docs/$(1)/$(1).$(5): +ifeq ($(6)-$$(MANUAL_XSLTPROC_IS_BROKEN),pdf-y) +$$(O)/docs/$(1)/$(1).$(6): $$(error PDF manual generation is disabled because of a bug in \ xsltproc. To be able to generate the PDF manual, you should \ build xsltproc from the libxslt sources >=1.1.29 and pass it \ to make through the command line: \ 'PATH=/path/to/custom-xsltproc/bin:$$$${PATH} make manual-pdf') else -$$(O)/docs/$(1)/$(1).$(5): $$($$(call UPPERCASE,$(1))_SOURCES) \ +$$(O)/docs/$(1)/$(1).$(6): $$($$(call UPPERCASE,$(1))_SOURCES) \ $(1)-check-dependencies \ - $(1)-check-dependencies-$(4) \ + $(1)-check-dependencies-$(5) \ $(1)-prepare-sources - $$(Q)$$(call MESSAGE,"Generating $(6) $(1)...") + $$(Q)$$(call MESSAGE,"Generating $(7) $(1)...") $$(Q)mkdir -p $$(@D) - $$(Q)a2x $(7) -f $(3) -d book -L \ + $$(Q)a2x $(8) -f $(4) -d book -L \ $$(foreach r,$$($(2)_RESSOURCES),-r $$(r)) \ - $$($(2)_$(3)_A2X_OPTS) \ - --asciidoc-opts="$$($(2)_$(3)_ASCIIDOC_OPTS)" \ + $$($(2)_$(4)_A2X_OPTS) \ + --asciidoc-opts="$$($(2)_$(4)_ASCIIDOC_OPTS)" \ $$(BUILD_DIR)/$(1)/$(1).txt # install the generated manual - $$($(2)_$(3)_INSTALL_CMDS) + $$($(2)_$(4)_INSTALL_CMDS) endif endef @@ -129,21 +130,26 @@ $$(BUILD_DIR)/$(pkgname): $(pkgname)-rsync: $$(BUILD_DIR)/$(pkgname) $$(Q)$$(call MESSAGE,"Preparing the $(pkgname) sources...") - $$(Q)rsync -a docs/$(pkgname)/ $$^ + $$(Q)rsync -a $(pkgdir) $$^ $(pkgname)-prepare-sources: $(pkgname)-rsync -$(call GENDOC_INNER,$(pkgname),$$(call UPPERCASE,$(pkgname)),xhtml,html,html,HTML,\ +$(call GENDOC_INNER,$(pkgname),$$(call UPPERCASE,$(pkgname)),$(pkgdir),xhtml,html,html,HTML,\ --xsltproc-opts "--stringparam toc.section.depth 1") -$(call GENDOC_INNER,$(pkgname),$$(call UPPERCASE,$(pkgname)),chunked,split-html,chunked,split HTML,\ + +$(call GENDOC_INNER,$(pkgname),$$(call UPPERCASE,$(pkgname)),$(pkgdir),chunked,split-html,chunked,split HTML,\ --xsltproc-opts "--stringparam toc.section.depth 1") + # dblatex needs to pass the '--maxvars ...' option to xsltproc to prevent it # from reaching the template recursion limit when processing the (long) target # package table and bailing out. -$(call GENDOC_INNER,$(pkgname),$$(call UPPERCASE,$(pkgname)),pdf,pdf,pdf,PDF,\ +$(call GENDOC_INNER,$(pkgname),$$(call UPPERCASE,$(pkgname)),$(pkgdir),pdf,pdf,pdf,PDF,\ --dblatex-opts "-P latex.output.revhistory=0 -x '--maxvars 100000'") -$(call GENDOC_INNER,$(pkgname),$$(call UPPERCASE,$(pkgname)),text,text,text,text) -$(call GENDOC_INNER,$(pkgname),$$(call UPPERCASE,$(pkgname)),epub,epub,epub,ePUB) + +$(call GENDOC_INNER,$(pkgname),$$(call UPPERCASE,$(pkgname)),$(pkgdir),text,text,text,text) + +$(call GENDOC_INNER,$(pkgname),$$(call UPPERCASE,$(pkgname)),$(pkgdir),epub,epub,epub,ePUB) + clean: $(pkgname)-clean $(pkgname)-clean: $$(Q)$$(RM) -rf $$(BUILD_DIR)/$(pkgname)
GENDOC_INNER still has one hard-coded path to the document's directory: the asciidoc .conf files. Add a new argument to GENDOC_INNER to pass the directory of the document. This makes for overly-long lines, but splitting is not possible, otherwise the first argument on the continuation line would get (at least) a leading space or tab, and that would break either or all of the variables names, the dependency rules, or the filenames we look for. Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr> Cc: Samuel Martin <s.martin49@gmail.com> Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com> --- docs/manual/manual.mk | 74 ++++++++++++++++++++++++++++----------------------- 1 file changed, 40 insertions(+), 34 deletions(-)