[PATCH 1/2] Documentation: Allow @@GIT_VERSION@@ in asciidoc.conf

[PATCH 1/2] Documentation: Allow @@GIT_VERSION@@ in asciidoc.conf

[Frank Lichtenheld]

Rename asciidoc.conf to asciidoc.conf.in and create
the former on build time after piping it through sed.

This is useful to allow us to include the git version
in the documentation.

Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>
---
 Documentation/Makefile         |   11 ++++++++---
 Documentation/asciidoc.conf    |   39 ---------------------------------------
 Documentation/asciidoc.conf.in |   39 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 47 insertions(+), 42 deletions(-)
 delete mode 100644 Documentation/asciidoc.conf
 create mode 100644 Documentation/asciidoc.conf.in

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 7c1c9e1..6197929 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -38,6 +38,7 @@ DOC_REF = origin/man
 
 -include ../config.mak.autogen
 -include ../config.mak
+-include ../GIT-VERSION-FILE
 
 #
 # Please note that there is a minor bug in asciidoc.
@@ -90,16 +91,20 @@ $(cmds_txt): cmd-list.perl $(MAN1_TXT)
 git.7 git.html: git.txt core-intro.txt
 
 clean:
-	rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep
+	rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep asciidoc.conf
 	rm -f $(cmds_txt)
 
-%.html : %.txt
+asciidoc.conf: asciidoc.conf.in
+	sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' $< >$@+
+	mv $@+ $@
+
+%.html : %.txt asciidoc.conf
 	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $<
 
 %.1 %.7 : %.xml
 	xmlto -m callouts.xsl man $<
 
-%.xml : %.txt
+%.xml : %.txt asciidoc.conf
 	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf $<
 
 user-manual.xml: user-manual.txt user-manual.conf
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
deleted file mode 100644
index 44b1ce4..0000000
--- a/Documentation/asciidoc.conf
+++ /dev/null
@@ -1,39 +0,0 @@
-## gitlink: macro
-#
-# Usage: gitlink:command[manpage-section]
-#
-# Note, {0} is the manpage section, while {target} is the command.
-#
-# Show GIT link as: <command>(<section>); if section is defined, else just show
-# the command.
-
-[attributes]
-caret=^
-startsb=&#91;
-endsb=&#93;
-tilde=&#126;
-
-ifdef::backend-docbook[]
-[gitlink-inlinemacro]
-{0%{target}}
-{0#<citerefentry>}
-{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
-{0#</citerefentry>}
-endif::backend-docbook[]
-
-ifdef::backend-docbook[]
-# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
-[listingblock]
-<example><title>{title}</title>
-<literallayout>
-|
-</literallayout>
-{title#}</example>
-endif::backend-docbook[]
-
-ifdef::backend-xhtml11[]
-[gitlink-inlinemacro]
-<a href="{target}.html">{target}{0?({0})}</a>
-endif::backend-xhtml11[]
-
-
diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in
new file mode 100644
index 0000000..44b1ce4
--- /dev/null
+++ b/Documentation/asciidoc.conf.in
@@ -0,0 +1,39 @@
+## gitlink: macro
+#
+# Usage: gitlink:command[manpage-section]
+#
+# Note, {0} is the manpage section, while {target} is the command.
+#
+# Show GIT link as: <command>(<section>); if section is defined, else just show
+# the command.
+
+[attributes]
+caret=^
+startsb=&#91;
+endsb=&#93;
+tilde=&#126;
+
+ifdef::backend-docbook[]
+[gitlink-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::backend-docbook[]
+# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
+[listingblock]
+<example><title>{title}</title>
+<literallayout>
+|
+</literallayout>
+{title#}</example>
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[gitlink-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
+
+
-- 
1.5.0.3

[PATCH 2/2] Documentation: Add version information to man pages

[Frank Lichtenheld]

Override the [header] macro of asciidoc's docbook
backend to add version information to the generated
man pages.

Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>
---
 Documentation/asciidoc.conf.in |   17 +++++++++++++++++
 1 files changed, 17 insertions(+), 0 deletions(-)

 I personally prefer to have this information available in the man page.

 Copying the whole [header] template is at best ugly but works. Better
 suggestions welcome.

diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in
index 44b1ce4..a86c31d 100644
--- a/Documentation/asciidoc.conf.in
+++ b/Documentation/asciidoc.conf.in
@@ -31,6 +31,23 @@ ifdef::backend-docbook[]
 {title#}</example>
 endif::backend-docbook[]
 
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">Git</refmiscinfo>
+<refmiscinfo class="version">@@GIT_VERSION@@</refmiscinfo>
+<refmiscinfo class="manual">Git Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <refname>{manname}</refname>
+  <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+
 ifdef::backend-xhtml11[]
 [gitlink-inlinemacro]
 <a href="{target}.html">{target}{0?({0})}</a>
-- 
1.5.0.3

Re: [PATCH 1/2] Documentation: Allow @@GIT_VERSION@@ in asciidoc.conf

[Junio C Hamano]

Frank Lichtenheld <frank@lichtenheld.de> writes:

> Rename asciidoc.conf to asciidoc.conf.in and create
> the former on build time after piping it through sed.
>
> This is useful to allow us to include the git version
> in the documentation.
>
> Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>
> ---
>  Documentation/Makefile         |   11 ++++++++---
>  Documentation/asciidoc.conf    |   39 ---------------------------------------
>  Documentation/asciidoc.conf.in |   39 +++++++++++++++++++++++++++++++++++++++
>  3 files changed, 47 insertions(+), 42 deletions(-)
>  delete mode 100644 Documentation/asciidoc.conf
>  create mode 100644 Documentation/asciidoc.conf.in

When sending a patch like this, please use "format-patch -M".

While this is attractive to some degree, *I* am grumpy.  Doesn't
this patch make html and man branches update all files _every_
time any small change is made to some documentation?

Re: [PATCH 1/2] Documentation: Allow @@GIT_VERSION@@ in asciidoc.conf

[Frank Lichtenheld]

On Fri, Mar 23, 2007 at 02:53:58PM -0700, Junio C Hamano wrote:
> Frank Lichtenheld <frank@lichtenheld.de> writes:
> 
> > Rename asciidoc.conf to asciidoc.conf.in and create
> > the former on build time after piping it through sed.
> >
> > This is useful to allow us to include the git version
> > in the documentation.

> When sending a patch like this, please use "format-patch -M".

Ok.

> While this is attractive to some degree, *I* am grumpy.  Doesn't
> this patch make html and man branches update all files _every_
> time any small change is made to some documentation?

Not with my patch; which is a bug in the patch though because
asciidoc.conf should really depend on GIT-VERSION-FILE.

Another possibility would be to replace the @@GIT_VERSION@@ in the man pages
themself and not in the asciidoc.conf. This would mean perhaps slightly
bigger changes to the build system, but running sed on all the files is of
course a lot faster than regenerating them with asciidoc.

What do you think?

Gruesse,
-- 
Frank Lichtenheld <frank@lichtenheld.de>
www: http://www.djpig.de/

Re: [PATCH 1/2] Documentation: Allow @@GIT_VERSION@@ in asciidoc.conf

[Brian Gernhardt]

On Mar 24, 2007, at 8:04 AM, Frank Lichtenheld wrote:

> On Fri, Mar 23, 2007 at 02:53:58PM -0700, Junio C Hamano wrote:
>
>> While this is attractive to some degree, *I* am grumpy.  Doesn't
>> this patch make html and man branches update all files _every_
>> time any small change is made to some documentation?
>
> Not with my patch; which is a bug in the patch though because
> asciidoc.conf should really depend on GIT-VERSION-FILE.
>
> Another possibility would be to replace the @@GIT_VERSION@@ in the  
> man pages
> themself and not in the asciidoc.conf. This would mean perhaps  
> slightly
> bigger changes to the build system, but running sed on all the  
> files is of
> course a lot faster than regenerating them with asciidoc.
>
> What do you think?

I think that any change that causes the documentation to be rebuilt  
without any change in the documentation is a horrible horrible idea.   
The asciidoc+xmlto/xsltproc chain is noticeably slow, and I don't  
think that having the version number is important enough to cause a  
rebuild.  Using sed is definitely better than doing a rebuild from  
the start at the cost of a fair amount of complexity (and extra  
files, but that's fairly negligible).

I'm not convinced of the need to have a version in every doc file,  
though.  The only use I can think of is to avoid version skew between  
the documentation and the programs, and that's easily solved by  
always building and installing them together.  Adding a version to  
just the main git man file might not be a bad mid-point though to  
make that skew easier to detect without having to rebuild *everything*.

~~ Brian

Re: [PATCH 1/2] Documentation: Allow @@GIT_VERSION@@ in asciidoc.conf

[Junio C Hamano]

Frank Lichtenheld <frank@lichtenheld.de> writes:

> On Fri, Mar 23, 2007 at 02:53:58PM -0700, Junio C Hamano wrote:
> ...
>> While this is attractive to some degree, *I* am grumpy.  Doesn't
>> this patch make html and man branches update all files _every_
>> time any small change is made to some documentation?
>
> Not with my patch; which is a bug in the patch though because
> asciidoc.conf should really depend on GIT-VERSION-FILE.
>
> Another possibility would be to replace the @@GIT_VERSION@@ in the man pages
> themself and not in the asciidoc.conf. This would mean perhaps slightly
> bigger changes to the build system, but running sed on all the files is of
> course a lot faster than regenerating them with asciidoc.
>
> What do you think?

Ideally, I would like a solution that does not update the
resulting git-foo.html if I keep running these two commands
every time the tip of 'master' in the official repo is updated:

	$ git pull ;# get the latest 'master' from the official repo
	$ make -C Documentation
	: do not run 'make clean' here for the next round

when the only difference in git-foo.html left from the previous
round and this make would regenerate are embedded datestamps and
git version numbers in the output (same for manpages).  In other
words, if the description for the command changed between v1.4.4
and v1.5.0 but did not change at all in v1.5.1, provided that
the above sequence "pull && make" is the only thing that is ever
run in the repository (especially, no 'make clean' is ever run),
I would prefer the generated document to say it was formatted on
the day v1.5.0 was pushed out to the official repository, and
the document describes git v1.5.0, even after I did the above
command sequence on the day v1.5.1 is pushed out.  That would
prevent html and man branches from getting meaningless updates
that only change the embedded version numbers and datestamps.

In other words, I do not want the git-cat-file.html to mention
"v1.5.1-rc1-53-g2499857", if what it says has not changed since
v1.2.0.  I'd prefer to see "v1.2.0" there.

Which probably means that the version number should not be part
of the dependencies of generated documents, as far as 'make's
rebuilding decision is concerned.

If somebody wants all documentation to say what the latest git
is, s/he can do "make clean && make", even if you arrange it to
allow me do the above, but the opposite is more cumbersome and
error prone.

[PATCH 1/2] Documentation: Replace @@GIT_VERSION@@ in documentation

[Frank Lichtenheld]

Include GIT-VERSION-FILE and replace @@GIT_VERSION@@ in
the HTML and XML asciidoc output. The documentation
doesn't depend on GIT-VERSION-FILE so it will not be
automatically rebuild if nothing else changed.

Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>
---
 Documentation/Makefile |   13 ++++++++++++-
 1 files changed, 12 insertions(+), 1 deletions(-)

 This should satisfy all of Junio's requirements.

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 7c1c9e1..64cc755 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -64,6 +64,11 @@ install: man
 	$(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir)
 
 
+../GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE
+	$(MAKE) -C ../ GIT-VERSION-FILE
+
+-include ../GIT-VERSION-FILE
+
 #
 # Determine "include::" file references in asciidoc files.
 #
@@ -90,17 +95,21 @@ $(cmds_txt): cmd-list.perl $(MAN1_TXT)
 git.7 git.html: git.txt core-intro.txt
 
 clean:
-	rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep
+	rm -f *.xml *.xml+ *.html *.html+ *.1 *.7 howto-index.txt howto/*.html doc.dep
 	rm -f $(cmds_txt)
 
 %.html : %.txt
 	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $<
+	sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' $@ >$@+
+	mv $@+ $@
 
 %.1 %.7 : %.xml
 	xmlto -m callouts.xsl man $<
 
 %.xml : %.txt
 	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf $<
+	sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' $@ >$@+
+	mv $@+ $@
 
 user-manual.xml: user-manual.txt user-manual.conf
 	$(ASCIIDOC) -b docbook -d book $<
@@ -136,3 +145,5 @@ install-webdoc : html
 
 quick-install:
 	sh ./install-doc-quick.sh $(DOC_REF) $(mandir)
+
+.PHONY: .FORCE-GIT-VERSION-FILE
-- 
1.5.0.3

[PATCH 2/2] Documentation: Add version information to man pages

[Frank Lichtenheld]

Override the [header] macro of asciidoc's docbook
backend to add version information to the generated
man pages.

Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>
---
 Documentation/asciidoc.conf |   17 +++++++++++++++++
 1 files changed, 17 insertions(+), 0 deletions(-)

 This one is unchanged but now applied to asciidoc.conf directly
 since asciidoc.conf.in is no longer necessary.

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 44b1ce4..a86c31d 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -31,6 +31,23 @@ ifdef::backend-docbook[]
 {title#}</example>
 endif::backend-docbook[]
 
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">Git</refmiscinfo>
+<refmiscinfo class="version">@@GIT_VERSION@@</refmiscinfo>
+<refmiscinfo class="manual">Git Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <refname>{manname}</refname>
+  <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+
 ifdef::backend-xhtml11[]
 [gitlink-inlinemacro]
 <a href="{target}.html">{target}{0?({0})}</a>
-- 
1.5.0.3

Re: [PATCH 2/2] Documentation: Add version information to man pages

[Junio C Hamano]

Frank Lichtenheld <frank@lichtenheld.de> writes:

> Override the [header] macro of asciidoc's docbook
> backend to add version information to the generated
> man pages.
>
> Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>

This breaks documents other than manpages by making everybody
unconditionally use the header you stole for doctype-manpage.

I needed this to unbreak it.

-- >8 --
[PATCH] Documentation: unbreak user-manual.

The previous one broke generated xml files for anything but manpages,
as it took the header for manpage unconditionally.  This fixes it.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---
 Documentation/asciidoc.conf |    2 ++
 1 files changed, 2 insertions(+), 0 deletions(-)

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index a86c31d..fa7dc94 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -31,6 +31,7 @@ ifdef::backend-docbook[]
 {title#}</example>
 endif::backend-docbook[]
 
+ifdef::doctype-manpage[]
 ifdef::backend-docbook[]
 [header]
 template::[header-declarations]
@@ -47,6 +48,7 @@ template::[header-declarations]
   <refpurpose>{manpurpose}</refpurpose>
 </refnamediv>
 endif::backend-docbook[]
+endif::doctype-manpage[]
 
 ifdef::backend-xhtml11[]
 [gitlink-inlinemacro]
-- 
1.5.1.rc2.620.g9a7ad

Re: [PATCH 1/2] Documentation: Replace @@GIT_VERSION@@ in documentation

[Junio C Hamano]

Frank Lichtenheld <frank@lichtenheld.de> writes:

>  %.html : %.txt
>  	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $<
> +	sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' $@ >$@+
> +	mv $@+ $@
>  
>  %.1 %.7 : %.xml
>  	xmlto -m callouts.xsl man $<
>  
>  %.xml : %.txt
>  	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf $<
> +	sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' $@ >$@+
> +	mv $@+ $@
>  
>  user-manual.xml: user-manual.txt user-manual.conf
>  	$(ASCIIDOC) -b docbook -d book $<

Sorry, but these compositions are wrong, as the build procedure
can die after asciidoc finishes but before it manages to finish
sed/mv.  The next make invocation would not know that the
previous one did not complete and would assume that the build
product %.html or %.xml are up to date.

Ideally if we can persuade asciidoc to output to its stdout, we
could do this:

	rm -f $@+ $@
        $(ASCIIDOC) --to-stdout ... | sed -e $(script) >$@+
        mv $@+ $@

Re: [PATCH 1/2] Documentation: Replace @@GIT_VERSION@@ in documentation

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> Ideally if we can persuade asciidoc to output to its stdout, we
> could do this:
>
> 	rm -f $@+ $@
>         $(ASCIIDOC) --to-stdout ... | sed -e $(script) >$@+
>         mv $@+ $@

like this perhaps.

---

 Documentation/Makefile |   12 ++++++++----
 1 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index de6cc6e..e82596d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -100,16 +100,20 @@ clean:
 	rm -f $(cmds_txt)
 
 %.html : %.txt
-	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $<
-	sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' $@ >$@+
+	rm -f $@+ $@
+	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
+		$(ASCIIDOC_EXTRA) -o - $< | \
+		sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' >$@+
 	mv $@+ $@
 
 %.1 %.7 : %.xml
 	xmlto -m callouts.xsl man $<
 
 %.xml : %.txt
-	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf $<
-	sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' $@ >$@+
+	rm -f $@+ $@
+	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
+		$(ASCIIDOC_EXTRA) -o - $< | \
+		sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' >$@+
 	mv $@+ $@
 
 user-manual.xml: user-manual.txt user-manual.conf