# [PATCH 2/2] Fix the building of gitman.info document 4 messages from 2008-12-29 to 2008-12-29. Participants: Teemu Likonen, Junio C Hamano. Thread: https://gitlist.dev/t/16905 ## Teemu Likonen, 2008-12-29 08:03 Subject: [PATCH 0/2] Fix the building of Info documents Message-ID: <1230537789-5376-1-git-send-email-tlikonen@iki.fi> URL: https://gitlist.dev/e/1230537789-5376-1-git-send-email-tlikonen%40iki.fi ``` 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(-) ``` ## Teemu Likonen, 2008-12-29 08:03 Subject: [PATCH 1/2] Fix the building of user-manual.texi and gitman.texi documents Message-ID: <1230537789-5376-2-git-send-email-tlikonen@iki.fi> URL: https://gitlist.dev/e/1230537789-5376-2-git-send-email-tlikonen%40iki.fi In-Reply-To: <1230537789-5376-1-git-send-email-tlikonen@iki.fi> ``` 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 --- 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 ``` ## Teemu Likonen, 2008-12-29 08:03 Subject: [PATCH 2/2] Fix the building of gitman.info document Message-ID: <1230537789-5376-3-git-send-email-tlikonen@iki.fi> URL: https://gitlist.dev/e/1230537789-5376-3-git-send-email-tlikonen%40iki.fi In-Reply-To: <1230537789-5376-2-git-send-email-tlikonen@iki.fi> ``` "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 --- 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 ``` ## Junio C Hamano, 2008-12-29 08:39 Subject: Re: [PATCH 1/2] Fix the building of user-manual.texi and gitman.texi documents Message-ID: <7veizre5nv.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7veizre5nv.fsf%40gitster.siamese.dyndns.org In-Reply-To: <1230537789-5376-2-git-send-email-tlikonen@iki.fi> ``` 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. ```