[PATCH] Add support for an info version of the user manual

[PATCH] Add support for an info version of the user manual

[David Kastrup]

These patches use docbook2x in order to create an info version of the
git user manual.  No existing Makefile targets (including "all") are
touched, so you need to explicitly say

make info
sudo make install-info

to get git.info created and installed.  If the info target directory
does not already contain a "dir" file, no directory entry is created.
This facilitates $(DESTDIR)-based installations.  The same could be
achieved with

sudo make INSTALL_INFO=: install-info

explicitly.

awk is used for patching up sub-par file and directory information in
the Texinfo file.  It would be cleaner to place the respective info
straight into user-manual.txt or the conversion configurations, but I
find myself unable to find out how to do this with Asciidoc/Texinfo.

Signed-off-by: David Kastrup <dak@gnu.org>
---
 Documentation/Makefile |   28 ++++++++++++++++++++++++++++
 Makefile               |    6 ++++++
 2 files changed, 34 insertions(+), 0 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 443114b..97ee067 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -44,6 +44,11 @@ INSTALL?=install
 RM ?= rm -f
 DOC_REF = origin/man
 
+infodir?=$(prefix)/share/info
+MAKEINFO=makeinfo
+INSTALL_INFO=install-info
+DOCBOOK2X_TEXI=docbook2x-texi
+
 -include ../config.mak.autogen
 -include ../config.mak
 
@@ -67,6 +72,8 @@ man1: $(DOC_MAN1)
 man5: $(DOC_MAN5)
 man7: $(DOC_MAN7)
 
+info: git.info
+
 install: man
 	$(INSTALL) -d -m755 $(DESTDIR)$(man1dir)
 	$(INSTALL) -d -m755 $(DESTDIR)$(man5dir)
@@ -75,6 +82,14 @@ install: man
 	$(INSTALL) -m644 $(DOC_MAN5) $(DESTDIR)$(man5dir)
 	$(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir)
 
+install-info: info
+	$(INSTALL) -d -m755 $(DESTDIR)$(infodir)
+	$(INSTALL) -m644 git.info $(DESTDIR)$(infodir)
+	if test -r $(DESTDIR)$(infodir)/dir; then \
+	  $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) git.info ;\
+	else \
+	  echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \
+	fi
 
 ../GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE
 	$(MAKE) -C ../ GIT-VERSION-FILE
@@ -138,6 +153,19 @@ XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
 user-manual.html: user-manual.xml
 	xsltproc $(XSLTOPTS) -o $@ $(XSLT) $<
 
+git.info: user-manual.xml
+	$(RM) $@ $*.texi
+	$(DOCBOOK2X_TEXI) user-manual.xml --to-stdout | \
+	awk '/^@setfilename/{$$2="git.info"};\
+	     /^@direntry/{print "@dircategory Development"; \
+	                  print "@direntry"; \
+	                  print "* Git: (git).           A fast distributed revision control system"; \
+			  print "@end direntry"}; \
+	     /^@direntry/,/^@end direntry/ { next }; \
+	     {print}' > $*.texi
+	$(MAKEINFO) --no-split $*.texi
+	$(RM) $*.texi
+
 howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
 	$(RM) $@+ $@
 	sh ./howto-index.sh $(wildcard howto/*.txt) >$@+
diff --git a/Makefile b/Makefile
index 2f3b9b2..b685c7e 100644
--- a/Makefile
+++ b/Makefile
@@ -913,6 +913,9 @@ perl/Makefile: perl/Git.pm perl/Makefile.PL GIT-CFLAGS
 doc:
 	$(MAKE) -C Documentation all
 
+info:
+	$(MAKE) -C Documentation info
+
 TAGS:
 	$(RM) TAGS
 	$(FIND) . -name '*.[hcS]' -print | xargs etags -a
@@ -1005,6 +1008,9 @@ endif
 install-doc:
 	$(MAKE) -C Documentation install
 
+install-info:
+	$(MAKE) -C Documentation install-info
+
 quick-install-doc:
 	$(MAKE) -C Documentation quick-install
 
-- 
1.5.3.rc4.21.ga63eb

Re: [PATCH] Add support for an info version of the user manual

[Jakub Narebski]

[Cc: David Kastrup <dak@gnu.org>, git@vger.kernel.org]

David Kastrup wrote:

> These patches use docbook2x in order to create an info version of the
> git user manual.
[...]
> ---
>  Documentation/Makefile |   28 ++++++++++++++++++++++++++++
>  Makefile               |    6 ++++++
>  2 files changed, 34 insertions(+), 0 deletions(-)
[...]

First, a note on patch: please use $(AWK) instead of 'awk', just in case.

It would be nice to add a paragraph about build requirements for info
version of Git User's Manual in the INSTALL file.

In the future we would probably want configure.ac to support --with-info or
something like that to install documentation in info format (it does
support --infodir), perhaps with awk autodetection and docbook2x
autodetection.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] Add support for an info version of the user manual

[Kalle Olavi Niemitalo]

David Kastrup <dak@gnu.org> posted to the git mailing list in 2007:

> awk is used for patching up sub-par file and directory information in
> the Texinfo file.  It would be cleaner to place the respective info
> straight into user-manual.txt or the conversion configurations, but I
> find myself unable to find out how to do this with Asciidoc/Texinfo.

I found how to do this, but it's not worth the trouble.

Apparently, there are two ways to specify the description for the
Info directory entry generated by docbook2X 0.8.3:

(a) Set it in the docbook2x-texi command line, with the option:

    -g description="A fast distributed revision control system"

    This could easily be placed in the Makefile.

(b) Add a /book/bookinfo/abstract[@role="texinfo-node"] element:

    <abstract role="texinfo-node"><simpara>A fast distributed
    revision control system</simpara></abstract>

    docbook2x-0.8.3/xslt/texi/menudescrip.xsl claims that the role
    should be "make-texinfo-node", but the template in that file
    actually looks for role="texinfo-node".  docbook2X 0.8.8
    documents the role correctly.

    The /book/bookinfo element currently comes from the [header]
    section in docbook.conf of AsciiDoc.  That docbook.conf does
    not currently provide a way to add an abstract like that.
    So, Git would have to override the whole header, unless
    such a feature were added to AsciiDoc.

Then, docbook2x-texi would take the title "Git User's Manual (for
version 1.5.3 or newer)" and convert it to "Git User_s Manual
[for version 1_5_3 or newer]", presumably to avoid some reserved
characters in Info.  To get a prettier title like "Git" in the
Info directory entry:

(a) A Git-specific XSL template could read the entry title from
    /book/bookinfo/titleabbrev, which would also have to be added
    to the header in the AsciiDoc configuration.

(b) Alternatively, the template could use a command-line parameter.
    Makefile would provide -g info-dir-title="Git", and the
    template would then use $info-dir-title.

Finally, to make the Info directory entry link to the right file,
one would have to add -g output-file=git to the docbook2x-texi
invocation.

In summary, it is certainly possible to make AsciiDoc and
docbook2X together generate the right kind of directory entry,
but I suspect the current Perl hack is more likely to survive
toolchain upgrades than a more proper implementation would be.
If the necessary features were added to the upstream AsciiDoc
and docbook2X, then things would be different, but I guess Git
wouldn't dare require new versions until after a year or so.

[PATCH] Add support for an info version of the user manual

[David Kastrup]

These patches use docbook2x in order to create an info version of the
git user manual.  No existing Makefile targets (including "all") are
touched, so you need to explicitly say

make info
sudo make install-info

to get git.info created and installed.  If the info target directory
does not already contain a "dir" file, no directory entry is created.
This facilitates $(DESTDIR)-based installations.  The same could be
achieved with

sudo make INSTALL_INFO=: install-info

explicitly.

awk is used for patching up sub-par file and directory information in
the Texinfo file.  It would be cleaner to place the respective info
straight into user-manual.txt or the conversion configurations, but I
find myself unable to find out how to do this with Asciidoc/Texinfo.

Signed-off-by: David Kastrup <dak@gnu.org>
---
 Documentation/Makefile |   28 ++++++++++++++++++++++++++++
 Makefile               |    6 ++++++
 2 files changed, 34 insertions(+), 0 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 443114b..5a5961b 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -44,6 +44,11 @@ INSTALL?=install
 RM ?= rm -f
 DOC_REF = origin/man
 
+infodir?=$(prefix)/share/info
+MAKEINFO=makeinfo
+INSTALL_INFO=install-info
+DOCBOOK2X_TEXI=docbook2x-texi
+
 -include ../config.mak.autogen
 -include ../config.mak
 
@@ -67,6 +72,8 @@ man1: $(DOC_MAN1)
 man5: $(DOC_MAN5)
 man7: $(DOC_MAN7)
 
+info: git.info
+
 install: man
 	$(INSTALL) -d -m755 $(DESTDIR)$(man1dir)
 	$(INSTALL) -d -m755 $(DESTDIR)$(man5dir)
@@ -75,6 +82,14 @@ install: man
 	$(INSTALL) -m644 $(DOC_MAN5) $(DESTDIR)$(man5dir)
 	$(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir)
 
+install-info: info
+	$(INSTALL) -d -m755 $(DESTDIR)$(infodir)
+	if test -r $(DESTDIR)$(infodir)/dir; then \
+	  $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) git.info ;\
+	else \
+	  $(INSTALL) -m644 git.info $(DESTDIR)$(infodir) ; \
+	  echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \
+	fi
 
 ../GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE
 	$(MAKE) -C ../ GIT-VERSION-FILE
@@ -138,6 +153,19 @@ XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
 user-manual.html: user-manual.xml
 	xsltproc $(XSLTOPTS) -o $@ $(XSLT) $<
 
+git.info: user-manual.xml
+	$(RM) $@ $*.texi
+	$(DOCBOOK2X_TEXI) user-manual.xml --to-stdout | \
+	awk '/^@setfilename/{$$2="git.info"};\
+	     /^@direntry/{print "@dircategory Development"; \
+	                  print "@direntry"; \
+	                  print "* Git: (git).           A fast distributed revision control system"; \
+			  print "@end direntry"}; \
+	     /^@direntry/,/^@end direntry/ { next }; \
+	     {print}' > $*.texi
+	$(MAKEINFO) --no-split $*.texi
+	$(RM) $*.texi
+
 howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
 	$(RM) $@+ $@
 	sh ./howto-index.sh $(wildcard howto/*.txt) >$@+
diff --git a/Makefile b/Makefile
index 2f3b9b2..b685c7e 100644
--- a/Makefile
+++ b/Makefile
@@ -913,6 +913,9 @@ perl/Makefile: perl/Git.pm perl/Makefile.PL GIT-CFLAGS
 doc:
 	$(MAKE) -C Documentation all
 
+info:
+	$(MAKE) -C Documentation info
+
 TAGS:
 	$(RM) TAGS
 	$(FIND) . -name '*.[hcS]' -print | xargs etags -a
@@ -1005,6 +1008,9 @@ endif
 install-doc:
 	$(MAKE) -C Documentation install
 
+install-info:
+	$(MAKE) -C Documentation install-info
+
 quick-install-doc:
 	$(MAKE) -C Documentation quick-install
 
-- 
1.5.3.rc4.21.ga63eb

Re: [PATCH] Add support for an info version of the user manual

[David Kastrup]

David Kastrup <dak@gnu.org> writes:

> These patches use docbook2x in order to create an info version of the
> git user manual.  No existing Makefile targets (including "all") are
> touched, so you need to explicitly say

Scrap that.  The installation case where install-info is used does not
work properly yet.  Another version coming up.

-- 
David Kastrup