On Mon, 25 Oct 2010, Jakub Narebski wrote:
> On Mon, 25 Oct 2010, Jeff King wrote:
>> On Mon, Oct 25, 2010 at 02:44:06PM +0200, Jakub Narebski wrote:
>>>> 2. You recursively follow includes via include::. This means that the
>>>> make rule is not accurate. E.g., try:
>>> [...]
>>> We do that: see 'doc.dep' target in Documentation/Makefile. We just
>>> need for this target to also add dependencies for config-vars.txt
>>> (perhaps separate mode for make-config-list.perl, or perhaps
>>> build-docdep.perl should be config-vars-src.txt aware...).
>>
>> Yeah, that would definitely work.
The part of patch (commit) touching Documentation/Makefile could look
like this:
-- 8< --
diff --git a/Documentation/Makefile b/Documentation/Makefile
index e117bc4..351aa9c 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -212,9 +212,12 @@ install-html: html
#
# Determine "include::" file references in asciidoc files.
#
-doc.dep : $(wildcard *.txt) build-docdep.perl
+doc.dep : $(wildcard *.txt) build-docdep.perl make-config-list.perl
$(QUIET_GEN)$(RM) $@+ $@ && \
$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \
+ $(PERL_PATH) ./make-config-list.perl --deps=config-vars.txt \
+ --mainlist=config-vars-src.txt $(MAN_TXT) \
+ >>$@+ $(QUIET_STDERR) && \
mv $@+ $@
-include doc.dep
@@ -320,6 +323,11 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
'$(SHELL_PATH_SQ)' ./howto-index.sh $(wildcard howto/*.txt) >$@+ && \
mv $@+ $@
+config-vars.txt: config-vars-src.txt $(MAN_TXT) make-config-list.perl
+ $(PERL_PATH) ./make-config-list.perl \
+ --mainlist=$< --ignore=$@ $(MAN_TXT) >$@+ && \
+ mv $@+ $@
+
$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
$(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt
-- >8 --
Note that while in rule for config-vars.txt target we can use automatic
variables, we have to spell filenames in full in the part of doc.dep
rules that generate dependency for config-vars.txt. Note also that we
have to keep those explicit and implicit filenames in sync across those
two rules.
> Though simpler would be just to not use or turn off following includes,
> as it turned out that it doesn't matter to follow includes in manpages:
> if we include with config variables, it is to also include it in
> config-vars-src.txt.
>
> Well, assuming that we don't have to follow includes in config-vars-src.txt;
> otherwise we have to generate line in doc.dep for that include anyway.
Decision time!!!
There are two possible approaches:
1. Don't follow includes in manpages (in manpage sources), and don't follow
includes in config-vars-src.txt
Advantages:
* Less code to write and maintain
* No need to keep filenames in rule for config-vars.txt and for doc.dep
in sync.
Disadvantages:
* Theoretically fragile: it depends on two assumptions:
A. If file included in manpage contains description of config vars,
then this file would be included also in config-vars-src.txt
B. For config variables inside file(s) included by config-vars-src.txt,
if they are present in individual manpage, it is done by inclusion
of said file.
Those assumptions are two sides of the same coin, and can be written
as: file included in manpagee can contain config variables if and only
if it is included in config-vars-src.txt
2. Follow includes both in manpages and in config-vars-src.txt, and
generate dependencies for config-vars.txt
Advantages:
* More generic solution
Disadvantages:
* Need to keep rules for doc.dep and for config-vars.txt in sync, as
described above
* config-vars.txt rule has more dependencies.
Now, which one to choose?
--
Jakub Narebski
Poland
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html