Re: [RFC PATCH v2 0/3] Documentation: refactor config variable descriptions

[Jakub Narebski <jnareb@gmail.com>]

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