[PATCH 0/2] Fix the building of Info documents

[PATCH 0/2] Fix the building of Info documents

[Teemu Likonen]

In these days Info documents are probably only used by Emacs users. I'm
one, so I wanted to fix the building of Git Info documents. And it's
even possible - to certain extent.

My real opinion is that the document conversion chain .txt - .xml -
.texi - .info. just can't work without a miracle. These patches
certainly don't do a miracle but they allow building an usable Info
version of the user manual and the man pages. As usual, there are
problems with markup conversions. For example, two dashes (--) in a
.texi file turn into one Ascii dash (-), so there are options like
"-interactive" and "-stat" in the Info documents. I wouldn't advertise
these documents very loudly to the public.

(My real real real opinion is that the GNU people should drop the Info
system and start using html instead. Html probably isn't a simple
drop-in replacement but at least it's a relevant format in 2008-2009.)


Teemu Likonen (2):
  Fix the building of user-manual.texi and gitman.texi documents
  Fix the building of gitman.info document

 Documentation/Makefile      |    9 +++++----
 Documentation/cat-texi.perl |    8 ++++++--
 2 files changed, 11 insertions(+), 6 deletions(-)

[PATCH 1/2] Fix the building of user-manual.texi and gitman.texi documents

[Teemu Likonen]

Previously "docbook2x-texi" failed to generate user-manual.texi and
gitman.texi files from .xml input files because "iconv" stopped at
"illegal input sequence" error. This was due to some UTF-8 octets in the
input .xml files. This patch adds option --encoding=UTF-8 for
"docbook2x-texi" to allow the building of .texi files complete.

Signed-off-by: Teemu Likonen <tlikonen@iki.fi>
---
 Documentation/Makefile |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index c34c1ca..c41a7b4 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -187,13 +187,14 @@ git.info: user-manual.texi
 
 user-manual.texi: user-manual.xml
 	$(RM) $@+ $@
-	$(DOCBOOK2X_TEXI) user-manual.xml --to-stdout | $(PERL_PATH) fix-texi.perl >$@+
+	$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout | \
+		$(PERL_PATH) fix-texi.perl >$@+
 	mv $@+ $@
 
 gitman.texi: $(MAN_XML) cat-texi.perl
 	$(RM) $@+ $@
-	($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --to-stdout $(xml);)) | \
-	$(PERL_PATH) cat-texi.perl $@ >$@+
+	($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
+		--to-stdout $(xml);)) | $(PERL_PATH) cat-texi.perl $@ >$@+
 	mv $@+ $@
 
 gitman.info: gitman.texi
-- 
1.6.1.16.gd45c5

[PATCH 2/2] Fix the building of gitman.info document

[Teemu Likonen]

"makeinfo" failed to generate gitman.info from gitman.texi input file
because the combined manual page file contains several nodes with the
same name (DESCRIPTION, OPTIONS, SEE ALSO etc.). An Info document should
contain unique node names.

This patch creates a simple (read: ugly) work-around by suppressing the
validation of the final Info file. Jumping to nodes in the Info document
still works but they are not very useful. Common man-page headings like
DESCRIPTION and OPTIONS appear in the Info node list and they point to
the man page where they appear first (that is git-add currently).

Also, this patch adds directory-entry information for Info document to
make the document appear in the top-level Info directory.

Signed-off-by: Teemu Likonen <tlikonen@iki.fi>
---
 Documentation/Makefile      |    2 +-
 Documentation/cat-texi.perl |    8 ++++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index c41a7b4..5cd8b63 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -198,7 +198,7 @@ gitman.texi: $(MAN_XML) cat-texi.perl
 	mv $@+ $@
 
 gitman.info: gitman.texi
-	$(MAKEINFO) --no-split $*.texi
+	$(MAKEINFO) --no-split --no-validate $*.texi
 
 $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml
 	$(RM) $@+ $@
diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl
index dbc133c..828ec62 100755
--- a/Documentation/cat-texi.perl
+++ b/Documentation/cat-texi.perl
@@ -18,8 +18,12 @@ close TMP;
 
 printf '\input texinfo
 @setfilename gitman.info
-@documentencoding us-ascii
-@node Top,,%s
+@documentencoding UTF-8
+@dircategory Development
+@direntry
+* Git Man Pages: (gitman).  Manual pages for Git revision control system
+@end direntry
+@node Top,,, (dir)
 @top Git Manual Pages
 @documentlanguage en
 @menu
-- 
1.6.1.16.gd45c5

Re: [PATCH 1/2] Fix the building of user-manual.texi and gitman.texi documents

[Junio C Hamano]

I do not build nor use info myself these days, so I'll apply the patches
but when somebody else screams I'll let you and that somebody else work on
improvements.

Thanks.